Skip to content

feat(export): restore original nested paths on OKF re-export#106

Merged
ethanj merged 6 commits into
mainfrom
feat/okf-nested-paths
Jun 15, 2026
Merged

feat(export): restore original nested paths on OKF re-export#106
ethanj merged 6 commits into
mainfrom
feat/okf-nested-paths

Conversation

@ethanj

@ethanj ethanj commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

What

Re-exporting an OKF bundle that was imported from nested paths now restores each imported foreign document to its original location (e.g. tables/customers.md) instead of flattening it to concepts/<slug>.md, with the index and inter-document links pointing at those paths. This resolves the deferred follow-up from the OKF round-trip work — a bundle now survives import → export with its layout and links intact.

  • Placement. A new resolver assigns each page its output path: native pages keep their slug-path; an imported page restores its x-okf.okfPath when that path is safe and uncontested, otherwise falls back to its slug-path with a warning. An ownership map guarantees a restored path can never displace another page.
  • Links. The link resolver is path-aware, so a native page linking an imported doc ([[tables-customers]]) emits the doc's real path (/tables/customers.md); on re-import that link reverses back to a wikilink, so it round-trips with no drift. Foreign documents' own markdown links are preserved verbatim and now resolve, since the files are restored to where the links point.

Why

It makes llmwiki a faithful OKF pass-through: a third-party bundle keeps its directory structure and cross-document links across a round-trip, not just its contents and frontmatter.

Safety

Imported okfPath values are untrusted (editable page frontmatter), so the exporter is hardened: an unsafe or colliding path falls back to the slug-path with a structured warning; every write is realpath-confined to the bundle; and the output directory is handled carefully — the bundle's real target is resolved through symlinks before any directory is created and refused if it is the filesystem root, the project root, or inside .git; a non-empty directory that isn't a recognized OKF bundle is refused rather than clobbered; and a recognized prior bundle is wholesale-cleared (refusing if it contains a nested .git) so stale files don't linger. External output directories remain supported.

Test plan

  • npx tsc --noEmit, npm run build, npm test (1663 passed), npx fallow (0 above threshold), dupes clean
  • Nested round-trip: a foreign tables/customers.md + a sibling linking it survive import → export at their exact paths with the link intact, and re-import
  • Native→foreign full cycle: [[tables-customers]]/tables/customers.md → back to [[tables-customers]]
  • Output-path resolution: ownership-map collisions (foreign-vs-native and foreign-vs-foreign), unsafe-path fallback with warning, exact-match reserved names (nested index.md allowed)
  • Output-dir safety: refusals for filesystem/project root, inside .git (asserted never created), a symlinked parent resolving into .git, a nested .git in a bundle, and a non-empty non-bundle dir; symlinked-subdir cleanup and stale-file cleanup
  • Backward compatibility: native-only bundles place every doc at <dir>/<slug>.md with unchanged TOC/links

ethanj and others added 6 commits June 15, 2026 14:59
…tolerance

isSafeOkfPath now rejects okfPaths with URL-unsafe characters so a foreign doc named with spaces or parens falls back to its slug-path instead of emitting malformed markdown links. Foreign-page ordering uses a real total order (okfPath, pageDirectory, slug). A stray .DS_Store/Thumbs.db no longer makes an output directory refuse export. Comment cleanups: external out is allowed, realpath confinement is a hard backstop, nested-.git scan cost, and the multi-hop foreign-link conversion nuance.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ethanj ethanj force-pushed the feat/okf-nested-paths branch from 3666c0b to ab93dad Compare June 15, 2026 23:15
@ethanj ethanj merged commit 4f25c81 into main Jun 15, 2026
3 checks passed
@ethanj ethanj deleted the feat/okf-nested-paths branch June 15, 2026 23:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant