@riebeckite/node 0.0.34 → 0.0.36

package/README.md

@@ -96,6 +96,32 @@ useful for inspection tooling; ordinary applications should use `scan()`.
 These helpers operate on logical content paths with `/` separators, not
 absolute filesystem paths.
 
+## Content mutations
+
+`FileSystemContentMutation` is the write-side adapter. It is separate from
+`ContentSource` and `ContentManager`: create a plan first, inspect its warnings
+and conflicts, then explicitly apply it.
+
+```ts
+import { FileSystemContentMutation } from "@riebeckite/node";
+
+const mutation = new FileSystemContentMutation("content");
+const plan = await mutation.plan([
+  { kind: "rename", from: "draft.md", to: "notes/published.md" },
+]);
+if (plan.conflicts.length === 0) await mutation.apply(plan);
+```
+
+Plans contain file fingerprints and are rejected when a file changes before
+apply. The adapter accepts create, update, delete, move, rename, frontmatter,
+batch, and binary asset operations. It writes a journal and original-file
+backups under `.riebeckite/mutations`. Call `recover(journalPath)` after an
+interrupted apply; recovery refuses files changed after the interrupted write.
+
+Logical paths reject traversal, Windows reserved names, invalid characters, and
+existing symbolic-link parents. Multi-file applies are staged and journaled but
+are not filesystem-atomic.
+
 ## Package boundary
 
 `@riebeckite/core` defines the portable `ContentSource` contract and content

package/README_ja.md

@@ -90,6 +90,31 @@ const { entries, exclusions } = await source.scanWithExclusions();
 これらのヘルパーは絶対ファイルシステムパスではなく、`/` 区切りの論理コンテンツパスを
 対象にします。
 
+## コンテンツ変更
+
+`FileSystemContentMutation` は書き込み側のアダプターです。`ContentSource` や
+`ContentManager` とは分離されており、まず Plan を作成して警告・競合を確認し、明示的に
+Apply します。
+
+```ts
+import { FileSystemContentMutation } from "@riebeckite/node";
+
+const mutation = new FileSystemContentMutation("content");
+const plan = await mutation.plan([
+  { kind: "rename", from: "draft.md", to: "notes/published.md" },
+]);
+if (plan.conflicts.length === 0) await mutation.apply(plan);
+```
+
+Plan にはファイルの fingerprint が含まれ、Apply 前に変更されていれば拒否されます。
+create、update、delete、move、rename、frontmatter、batch、バイナリアセットを扱えます。
+中断した Apply に備えて `.riebeckite/mutations` に Journal と元ファイルの Backup を残します。
+`recover(journalPath)` は中断後に変更されたファイルを復旧せず、競合として返します。
+
+論理パスでは traversal、Windows の予約名、不正な文字、既存のシンボリックリンクを
+経由する親ディレクトリを拒否します。複数ファイルの Apply は staging と Journal を使いますが、
+ファイルシステム全体の原子性は保証しません。
+
 ## パッケージ境界
 
 `@riebeckite/core` は移植可能な `ContentSource` 契約とコンテンツパイプラインを

package/dist/index.d.ts

@@ -1,2 +1,9 @@
+export type { ContentSourceConfig } from "./src/content_source_factory.js";
+export { createContentSource } from "./src/content_source_factory.js";
+export type { ContentMigrationApplyOptions, ContentMigrationApplyResult, ContentMigrationPlan, ContentMigrationPlanFile, ContentMigrationRecoverOptions, ContentMigrationRecoveryResult, ContentMigrationRollbackOptions, ContentMigrationRollbackOutcome, ContentMigrationStatusEntry, ContentMigrationStatusReport, ContentMigrationVerification, FileSystemContentMigrationOptions, FutureContentSource, } from "./src/file_system_content_migration.js";
+export { createFutureContentSource, FileSystemContentMigration, fingerprintContentFiles, } from "./src/file_system_content_migration.js";
+export type { FileSystemContentMutationOptions } from "./src/file_system_content_mutation.js";
+export { FileSystemContentMutation } from "./src/file_system_content_mutation.js";
 export type { ContentSourceExclusion, ContentSourceScan, } from "./src/file_system_content_source.js";
 export { FileSystemContentSource, INTERNAL_CONTENT_IGNORE_PATTERNS, isIgnoredContentPath, matchContentExcludePattern, } from "./src/file_system_content_source.js";
+export { isPathInsideDirectory, toLogicalPath } from "./src/path_helpers.js";