Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): keep fragments and Windows paths in doc links (PRD-8112) (#4826)
Abrahama5661005d404
diff --git a/.changeset/prd-8112-doc-link-fragments.md b/.changeset/prd-8112-doc-link-fragments.mdnew file mode 100644index 000000000..39addd0d0--- /dev/null+++ b/.changeset/prd-8112-doc-link-fragments.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Links in an agent conversation that point at a document in your project now keep their `#heading` fragment, whether written as a markdown link, a backticked path or a bare path in prose. Windows paths resolve as well.diff --git a/knip.config.ts b/knip.config.tsindex 5b8951125..659eef71e 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -143,11 +143,15 @@ export default {'packages/server': {entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],project: 'src/**',- ignoreDependencies: ['@types/shell-quote'],+ ignoreDependencies: [+ '@types/shell-quote',+ ],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],- ignoreDependencies: ['yjs'],+ ignoreDependencies: [+ 'yjs',+ ],},'packages/desktop': {entry: [diff --git a/packages/app/src/components/acp/AgentMarkdown.dom.test.tsx b/packages/app/src/components/acp/AgentMarkdown.dom.test.tsxindex 230e2e5c8..dac2a2173 100644--- a/packages/app/src/components/acp/AgentMarkdown.dom.test.tsx+++ b/packages/app/src/components/acp/AgentMarkdown.dom.test.tsx@@ -211,6 +211,45 @@ describe('AgentMarkdown doc-path links', () => {expect(link?.textContent).toBe('docs/intro.mdx');});+ test('a reference-style link stays literal text — the renderer never joins a definition to its reference', () => {+ const { container } = renderWithResolver(+ 'see [the report][r]\n\n[r]: public/open-knowledge/reports/foo/REPORT.md',+ );+ expect(container.querySelector('a')).toBeNull();+ expect(container.textContent).toContain('[the report][r]');+ });++ test('a heading fragment on a doc link survives onto the in-app route', () => {+ const { container } = renderWithResolver(+ '[findings](public/open-knowledge/reports/foo/REPORT.md#findings)',+ );+ const anchor = container.querySelector('[data-testid="agent-thread-doc-link"]');+ expect(anchor?.getAttribute('href')).toBe('#/reports/foo/REPORT#findings');+ });++ test('a fragment on a prose or backticked path lands on the in-app route as well', () => {+ const { container } = renderWithResolver(+ 'see public/open-knowledge/reports/foo/REPORT.md#findings and `reports/foo/REPORT.md#root-cause`',+ );+ const hrefs = Array.from(+ container.querySelectorAll('[data-testid="agent-thread-doc-link"]'),+ (a) => a.getAttribute('href'),+ );+ expect(hrefs).toEqual(['#/reports/foo/REPORT#findings', '#/reports/foo/REPORT#root-cause']);+ expect(container.textContent).toContain(+ 'REPORT.md#findings and reports/foo/REPORT.md#root-cause',+ );+ });++ test('a javascript: href never renders as a link, percent-encoded or not', () => {+ for (const href of ['javascript:alert(1)', 'javascript%3Aalert(1)']) {+ const { container, unmount } = renderWithResolver(`[run](${href})`);+ expect(container.querySelector('a[href^="javascript"]'), href).toBeNull();+ expect(container.querySelector('[data-testid="agent-thread-doc-link"]'), href).toBeNull();+ unmount();+ }+ });+test('an external link keeps target=_blank + Streamdown link styling', () => {const { container } = renderWithResolver('see [docs](https://example.com/x)');const link = container.querySelector('a[href="https://example.com/x"]');diff --git a/packages/app/src/components/acp/doc-path-links.test.ts b/packages/app/src/components/acp/doc-path-links.test.tsindex 090d6369b..827ef0494 100644--- a/packages/app/src/components/acp/doc-path-links.test.ts+++ b/packages/app/src/components/acp/doc-path-links.test.ts@@ -341,7 +341,6 @@ describe('remarkDocPathLinks', () => {'public/open-knowledge/reports/foo/REPORT.md','/Users/abraham/repo/public/open-knowledge/reports/foo/REPORT.md','file:///Users/abraham/repo/public/open-knowledge/reports/foo/REPORT.md',- 'reports/foo/REPORT.md#findings','public/open-knowledge/reports/foo/REPORT%2Emd',]) {const tree = makeTree([@@ -362,6 +361,9 @@ describe('remarkDocPathLinks', () => {for (const href of ['public/open-knowledge/reports/nope/REPORT.md','mailto:[email protected]',+ 'javascript:alert(1)',+ 'javascript%3Aalert(1)',+ '//example.com/reports/foo/REPORT.md','#/already/in-app',]) {const tree = makeTree([@@ -375,4 +377,138 @@ describe('remarkDocPathLinks', () => {expect(tree.children?.[0]?.children?.[0]?.url, href).toBe(href);}});++ test('a scheme-shaped href never resolves, encoded or not, even when a page would match it', () => {+ const resolveOdd = buildDocPathResolver({+ workspace,+ pages: new Set(['myapp:reports/foo/REPORT']),+ });+ for (const href of ['myapp:reports/foo/REPORT.md', 'myapp%3Areports/foo/REPORT.md']) {+ const tree = makeTree([+ {+ type: 'paragraph',+ children: [{ type: 'link', url: href, children: [{ type: 'text', value: 'x' }] }],+ },+ ]);+ setDocPathResolver(resolveOdd);+ remarkDocPathLinks()()(tree);+ expect(tree.children?.[0]?.children?.[0]?.url, href).toBe(href);+ }+ });++ test('a link fragment rides along onto the in-app route', () => {+ const cases: ReadonlyArray<readonly [string, string]> = [+ ['reports/foo/REPORT.md#findings', '#/reports/foo/REPORT#findings'],+ ['public/open-knowledge/reports/foo/REPORT.md#root-cause', '#/reports/foo/REPORT#root-cause'],+ ['reports/foo/REPORT.md#', '#/reports/foo/REPORT'],+ ];+ for (const [href, expected] of cases) {+ const tree = makeTree([+ {+ type: 'paragraph',+ children: [{ type: 'link', url: href, children: [{ type: 'text', value: 'x' }] }],+ },+ ]);+ setDocPathResolver(resolve);+ remarkDocPathLinks()()(tree);+ expect(tree.children?.[0]?.children?.[0]?.url, href).toBe(expected);+ }+ });++ test('a fragment on a backticked or prose path rides along too', () => {+ const tree = makeTree([+ {+ type: 'paragraph',+ children: [+ { type: 'text', value: 'see reports/foo/REPORT.md#findings and ' },+ { type: 'inlineCode', value: 'reports/foo/REPORT.md#root-cause' },+ { type: 'text', value: ' or reports/foo/REPORT.md# alone' },+ ],+ },+ ]);+ setDocPathResolver(resolve);+ remarkDocPathLinks()()(tree);+ const kids = tree.children?.[0]?.children ?? [];+ expect(kids.map((k) => k.type)).toEqual([+ 'text',+ 'link',+ 'text',+ 'link',+ 'text',+ 'link',+ 'text',+ ]);+ expect(kids[1]?.url).toBe('#/reports/foo/REPORT#findings');+ expect(kids[1]?.children?.[0]).toEqual({+ type: 'text',+ value: 'reports/foo/REPORT.md#findings',+ });+ expect(kids[3]?.url).toBe('#/reports/foo/REPORT#root-cause');+ expect(kids[3]?.children?.[0]?.type).toBe('inlineCode');+ expect(kids[5]?.url).toBe('#/reports/foo/REPORT');+ expect(kids[6]).toEqual({ type: 'text', value: '# alone' });+ });++ test('a Windows path in a link reaches the resolver instead of reading as a scheme', () => {+ const resolveWindows = buildDocPathResolver({+ workspace: windowsWorkspace,+ pages: new Set(['reports/foo/REPORT']),+ });+ for (const href of [+ 'C:\\Users\\abraham\\repo\\public\\open-knowledge\\reports\\foo\\REPORT.md',+ 'file:///C:/Users/abraham/repo/public/open-knowledge/reports/foo/REPORT.md',+ ]) {+ const tree = makeTree([+ {+ type: 'paragraph',+ children: [{ type: 'link', url: href, children: [{ type: 'text', value: 'x' }] }],+ },+ ]);+ setDocPathResolver(resolveWindows);+ remarkDocPathLinks()()(tree);+ expect(tree.children?.[0]?.children?.[0]?.url, href).toBe('#/reports/foo/REPORT');+ }+ });++ test('a reference-style link resolves through its definition', () => {+ const tree = makeTree([+ {+ type: 'paragraph',+ children: [{ type: 'linkReference', children: [{ type: 'text', value: 'the report' }] }],+ },+ { type: 'definition', url: 'public/open-knowledge/reports/foo/REPORT.md', title: null },+ ]);+ setDocPathResolver(resolve);+ remarkDocPathLinks()()(tree);+ expect(tree.children?.[1]?.url).toBe('#/reports/foo/REPORT');+ expect(tree.children?.[0]?.children?.[0]?.type).toBe('linkReference');+ });++ test('a malformed percent-escape is taken literally, and later links still resolve', () => {+ const resolveLiteral = buildDocPathResolver({+ workspace,+ pages: new Set(['reports/100%/REPORT', 'reports/foo/REPORT']),+ });+ const link = (url: string): MdastNode => ({+ type: 'link',+ url,+ children: [{ type: 'text', value: 'x' }],+ });+ const tree = makeTree([+ {+ type: 'paragraph',+ children: [+ link('reports/100%/REPORT.md'),+ link('reports/foo%zz/REPORT.md'),+ link('reports/foo/REPORT.md'),+ ],+ },+ ]);+ setDocPathResolver(resolveLiteral);+ remarkDocPathLinks()()(tree);+ const kids = tree.children?.[0]?.children ?? [];+ expect(kids[0]?.url).toBe('#/reports/100%25/REPORT');+ expect(kids[1]?.url).toBe('reports/foo%zz/REPORT.md');+ expect(kids[2]?.url).toBe('#/reports/foo/REPORT');+ });});diff --git a/packages/app/src/components/acp/doc-path-links.ts b/packages/app/src/components/acp/doc-path-links.tsindex 1bc88ca5a..7dbedbe45 100644--- a/packages/app/src/components/acp/doc-path-links.ts+++ b/packages/app/src/components/acp/doc-path-links.ts@@ -1,10 +1,11 @@+import { decodeHrefPath, isExternalHref } from '@inkeep/open-knowledge-core';import { docNameFromAbsolutePath } from '@/components/acp/follow-file';import { hashFromDocName } from '@/lib/doc-hash';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/g;+const DOC_PATH_REGEX = /(?<![A-Za-z0-9_./@-])[A-Za-z0-9_./@-]+\.(?:md|mdx)\b(?:#[A-Za-z0-9_-]+)?/g;export interface BuildDocPathResolverInput {readonly workspace: Workspace | null;@@ -102,9 +103,11 @@ function rewriteNode(node: MdastNode | undefined, resolver: DocPathResolver): voconst next: MdastNode[] = [];for (const child of children) {if (child === undefined || child === null) continue;- if (child.type === 'link') {- const doc = typeof child.url === 'string' ? resolveLinkUrl(child.url, resolver) : null;- next.push(doc === null ? child : { ...child, url: hashFromDocName(doc) });+ if (child.type === 'link' || child.type === 'definition') {+ const target = typeof child.url === 'string' ? resolveLinkUrl(child.url, resolver) : null;+ next.push(+ target === null ? child : { ...child, url: hashFromDocName(target.docName, target.anchor) },+ );continue;}if (child.type === 'text' && typeof child.value === 'string') {@@ -112,13 +115,13 @@ function rewriteNode(node: MdastNode | undefined, resolver: DocPathResolver): vocontinue;}if (child.type === 'inlineCode' && typeof child.value === 'string') {- const doc = resolver(child.value.trim());- if (doc === null) {+ const target = resolveTarget(child.value.trim(), resolver);+ if (target === null) {next.push(child);} else {next.push({type: 'link',- url: hashFromDocName(doc),+ url: hashFromDocName(target.docName, target.anchor),title: null,children: [child],});@@ -132,19 +135,42 @@ function rewriteNode(node: MdastNode | undefined, resolver: DocPathResolver): vo}const FILE_SCHEME = /^file:\/\//i;-const OTHER_SCHEME = /^[a-z][a-z0-9+.-]*:/i;--function resolveLinkUrl(url: string, resolver: DocPathResolver): string | null {- if (url.startsWith('#')) return null;- const path = FILE_SCHEME.test(url) ? url.replace(FILE_SCHEME, '') : url;- if (OTHER_SCHEME.test(path)) return null;- let decoded = path;- try {- decoded = decodeURIComponent(path);- } catch {- return null;- }- return resolver(decoded);+const FILE_DRIVE_SLASH = /^\/(?=[a-z]:(?:$|[/\\?]))/i;+const WINDOWS_DRIVE = /^[a-z]:(?:$|[/\\?])/i;++interface LinkTarget {+ docName: string;+ anchor: string | null;+}++function splitFragment(candidate: string): { path: string; anchor: string | null } {+ const hashIdx = candidate.indexOf('#');+ if (hashIdx === -1) return { path: candidate, anchor: null };+ return { path: candidate.slice(0, hashIdx), anchor: candidate.slice(hashIdx + 1) || null };+}++function resolveTarget(candidate: string, resolver: DocPathResolver): LinkTarget | null {+ const { path, anchor } = splitFragment(candidate);+ if (path === '') return null;+ const docName = resolver(path);+ return docName === null ? null : { docName, anchor };+}++function resolveLinkUrl(url: string, resolver: DocPathResolver): LinkTarget | null {+ const { path: rawPath, anchor } = splitFragment(url);+ if (rawPath === '') return null;+ const path = FILE_SCHEME.test(rawPath)+ ? rawPath.replace(FILE_SCHEME, '').replace(FILE_DRIVE_SLASH, '')+ : rawPath;+ if (isForeignScheme(path)) return null;+ const decoded = decodeHrefPath(path);+ if (isForeignScheme(decoded)) return null;+ const docName = resolver(decoded);+ return docName === null ? null : { docName, anchor };+}++function isForeignScheme(path: string): boolean {+ return isExternalHref(path) && !WINDOWS_DRIVE.test(path);}function splitTextByPaths(value: string, resolver: DocPathResolver): MdastNode[] {@@ -155,14 +181,14 @@ function splitTextByPaths(value: string, resolver: DocPathResolver): MdastNode[]while (match !== null) {const [candidate] = match;const start = match.index;- const doc = resolver(candidate);- if (doc !== null) {+ const target = resolveTarget(candidate, resolver);+ if (target !== null) {if (start > cursor) {out.push({ type: 'text', value: value.slice(cursor, start) });}out.push({type: 'link',- url: hashFromDocName(doc),+ url: hashFromDocName(target.docName, target.anchor),title: null,children: [{ type: 'text', value: candidate }],});diff --git a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts b/packages/app/tests/integration/bug3-source-mode-writeback.test.tsindex 8a60e5826..a28cc2b18 100644--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'node:fs';import { join } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';diff --git a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts b/packages/app/tests/integration/indented-jsx-byte-sacred.test.tsindex 6fcdc23f2..4fc2c11f9 100644--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts@@ -1,3 +1,4 @@+import { setTimeout as wait } from 'node:timers/promises';import { normalizeBridge } from '@inkeep/open-knowledge-core';import { updateYFragment } from '@tiptap/y-tiptap';diff --git a/packages/app/tests/integration/interior-edit-freshness.test.ts b/packages/app/tests/integration/interior-edit-freshness.test.tsindex 40b5cdfd6..9f2f6feb6 100644--- a/packages/app/tests/integration/interior-edit-freshness.test.ts+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts@@ -1,3 +1,4 @@+import { setTimeout as wait } from 'node:timers/promises';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';import { afterAll, beforeAll, describe, expect, test } from 'vitest';diff --git a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts b/packages/app/tests/integration/keystroke-cadence-danger-space.test.tsindex 93666af70..2a085742b 100644--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts@@ -1,3 +1,4 @@+import { setTimeout as wait } from 'node:timers/promises';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';import { afterAll, beforeAll, describe, expect, test } from 'vitest';diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.tsindex 867598d34..878d5196b 100644--- a/packages/app/tests/integration/producer-guard-wiring.test.ts+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts@@ -1,3 +1,4 @@+import { setTimeout as wait } from 'node:timers/promises';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';import { afterAll, beforeAll, describe, expect, test } from 'vitest';diff --git a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.tsindex 0970ac12f..4ada3cf26 100644--- a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts+++ b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts@@ -1,3 +1,4 @@+import { randomUUID } from 'node:crypto';import { afterEach, describe, expect, test } from 'vitest';import { agentWriteMd, createTestServer, type TestServer } from './test-harness';diff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.tsindex b632185e1..cbe2b705f 100644--- a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts@@ -1,3 +1,4 @@+import { execFileSync } from 'node:child_process';import { randomUUID } from 'node:crypto';import { join } from 'node:path';diff --git a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.tsindex c530ce4ba..89bc9b4d9 100644--- a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts+++ b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts@@ -1,3 +1,4 @@+import { randomUUID } from 'node:crypto';import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';import type * as Y from 'yjs';diff --git a/packages/app/tests/integration/undo-after-rollback.test.ts b/packages/app/tests/integration/undo-after-rollback.test.tsindex d3767adc9..a78aeb0e4 100644--- a/packages/app/tests/integration/undo-after-rollback.test.ts+++ b/packages/app/tests/integration/undo-after-rollback.test.ts@@ -1,3 +1,4 @@+import { ROLLBACK_ORIGIN } from '@inkeep/open-knowledge-server';import { afterAll, beforeAll, describe, expect, test } from 'vitest';import * as Y from 'yjs';diff --git a/packages/app/tests/integration/undo-recycle-reset.test.ts b/packages/app/tests/integration/undo-recycle-reset.test.tsindex b076f955c..e7cc69c3f 100644--- a/packages/app/tests/integration/undo-recycle-reset.test.ts+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts@@ -1,3 +1,4 @@+import { writeFileSync } from 'node:fs';import { join } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';diff --git a/packages/app/tests/integration/undo-rederive-survival.test.ts b/packages/app/tests/integration/undo-rederive-survival.test.tsindex 7935e35f8..9ddcd0730 100644--- a/packages/app/tests/integration/undo-rederive-survival.test.ts+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts@@ -1,3 +1,4 @@+import { prependFrontmatter } from '@inkeep/open-knowledge-core';import { Plugin, PluginKey } from '@tiptap/pm/state';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.tsindex f4cc8a286..2a597ec3d 100644--- a/packages/core/src/bridge/compose.ts+++ b/packages/core/src/bridge/compose.ts@@ -1,3 +1,4 @@+import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex 8fb428b90..01ef76a9f 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,3 +1,4 @@+import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex fc267cbea..fb0ba5a7c 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex bfd7e3109..fa3cfcd86 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 4d3250d3a..8be632ba4 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,3 +1,4 @@+export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');