feat(export): restore original nested paths on OKF re-export#106
Merged
Conversation
…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>
3666c0b to
ab93dad
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 toconcepts/<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.x-okf.okfPathwhen 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.[[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
okfPathvalues 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 cleantables/customers.md+ a sibling linking it survive import → export at their exact paths with the link intact, and re-import[[tables-customers]]→/tables/customers.md→ back to[[tables-customers]]index.mdallowed).git(asserted never created), a symlinked parent resolving into.git, a nested.gitin a bundle, and a non-empty non-bundle dir; symlinked-subdir cleanup and stale-file cleanup<dir>/<slug>.mdwith unchanged TOC/links