@riebeckite/node 0.0.34 → 0.0.36

package/dist/src/content_source_factory.d.ts

@@ -0,0 +1,7 @@
+import type { ContentSource } from "@riebeckite/core";
+export type ContentSourceConfig = {
+    readonly source?: ContentSource;
+    readonly directory: string;
+    readonly exclude?: readonly string[];
+};
+export declare function createContentSource(config: ContentSourceConfig, directory?: string): ContentSource;

package/dist/src/file_system_content_migration.d.ts

@@ -0,0 +1,48 @@
+import { type ContentMigrationHistory, type ContentMigrationListEntry, type ContentMutationFileChange, type ContentSource } from "@riebeckite/core";
+import type { ContentMigrationApplyOptions, ContentMigrationApplyResult, ContentMigrationPlan, ContentMigrationRecoverOptions, ContentMigrationRecoveryResult, ContentMigrationRollbackOptions, ContentMigrationRollbackOutcome, ContentMigrationStatusReport, FileSystemContentMigrationOptions, FutureContentSource } from "./file_system_content_migration_types.js";
+export type { ContentMigrationApplyOptions, ContentMigrationApplyResult, ContentMigrationPlan, ContentMigrationPlanFile, ContentMigrationRecoverOptions, ContentMigrationRecoveryResult, ContentMigrationRollbackOptions, ContentMigrationRollbackOutcome, ContentMigrationStatusEntry, ContentMigrationStatusReport, ContentMigrationVerification, FileSystemContentMigrationOptions, FutureContentSource, } from "./file_system_content_migration_types.js";
+export declare class FileSystemContentMigration {
+    private readonly options;
+    private readonly mutation;
+    private readonly source;
+    constructor(options: FileSystemContentMigrationOptions);
+    private get contentDirectory();
+    plan(options?: {
+        readonly ids?: readonly string[];
+    }): Promise<ContentMigrationPlan>;
+    savePlan(plan: ContentMigrationPlan, outputPath?: string): Promise<string>;
+    loadPlan(planPath: string): Promise<ContentMigrationPlan>;
+    history(options?: {
+        readonly limit?: number;
+    }): Promise<ContentMigrationHistory>;
+    list(): Promise<readonly ContentMigrationListEntry[]>;
+    apply(options?: ContentMigrationApplyOptions): Promise<ContentMigrationApplyResult>;
+    status(): Promise<ContentMigrationStatusReport>;
+    recover(options?: ContentMigrationRecoverOptions): Promise<ContentMigrationRecoveryResult>;
+    rollback(options: ContentMigrationRollbackOptions): Promise<ContentMigrationRollbackOutcome>;
+    private reconcile;
+    private preflight;
+    private stateWith;
+    private supersede;
+    private setStatuses;
+    private appendHistory;
+    private appendHistoryForRecords;
+    private failedJournal;
+    private currentContentFingerprint;
+    private readState;
+    private writeState;
+    private readHistory;
+    private writeHistory;
+    private relativeToContent;
+    private absoluteFromContent;
+    private acquireLock;
+    private tryAnalyze;
+    private analyze;
+    private redirectOperations;
+    private verify;
+}
+export declare function createFutureContentSource(base: ContentSource, changes: readonly ContentMutationFileChange[]): FutureContentSource;
+export declare function fingerprintContentFiles(files: readonly {
+    readonly path: string;
+    readonly content: string | Uint8Array;
+}[]): string;

package/dist/src/file_system_content_migration_helpers.d.ts

@@ -0,0 +1,53 @@
+import type { ContentManifest, ContentManifestEntry, ContentMigrationBatch, ContentMigrationDiagnostic, ContentMigrationRecord, ContentMutationFileChange, ContentMutationOperation, ResolvedRiebeckiteConfig } from "@riebeckite/core";
+import type { ContentMigrationPlan } from "./file_system_content_migration_types.js";
+export declare function redirectFieldFromConfig(config: ResolvedRiebeckiteConfig | undefined): string;
+export declare function fingerprintFiles(files: readonly {
+    readonly path: string;
+    readonly content: string | Uint8Array;
+}[]): string;
+export declare function fingerprintMutationPlan(operations: readonly ContentMutationOperation[], changes: readonly ContentMutationFileChange[]): string;
+export declare function fingerprintPlan(input: {
+    readonly migrations: readonly {
+        readonly id: string;
+        readonly version: number;
+        readonly fingerprint: string;
+    }[];
+    readonly baseContentFingerprint: string;
+    readonly mutationPlanFingerprint: string;
+    readonly operations: readonly ContentMutationOperation[];
+    readonly diagnostics: readonly ContentMigrationDiagnostic[];
+    readonly conflicts: readonly ContentMigrationDiagnostic[];
+}): string;
+export declare function canonicalJson(value: unknown): string;
+export declare function sortValue(value: unknown): unknown;
+export declare function findEntry(manifest: ContentManifest, contentPath: string): ContentManifestEntry | undefined;
+export declare function changedFrontmatterKeys(file: ContentMigrationBatch["files"][number]): Set<string>;
+export declare function diagnosticKey(diagnostic: {
+    readonly code: string;
+    readonly filePath?: string;
+    readonly target?: string;
+}): string;
+export declare function mutationIssue(issue: {
+    readonly severity: "warning" | "error";
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+}, severity: "warning" | "error"): ContentMigrationDiagnostic;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function sameMigrationPlan(left: ContentMigrationPlan, right: ContentMigrationPlan): boolean;
+export declare function isAppliedRecord(record: ContentMigrationRecord | undefined, fingerprint: string): boolean;
+export type JournalSnapshot = {
+    readonly state: string;
+    readonly changes: readonly {
+        readonly path: string;
+        readonly afterFingerprint: string | null;
+    }[];
+};
+export declare function readJournalSnapshot(journalPath: string): Promise<JournalSnapshot | undefined>;
+export declare function journalMatchesApplied(contentDirectory: string, journal: JournalSnapshot): Promise<boolean>;
+export declare function isWithin(root: string, target: string): boolean;
+export declare function exists(file: string): Promise<boolean>;
+export declare function staleLockContent(lockPath: string): Promise<string | null>;
+export declare function errorMessage(error: unknown): string;
+export declare function sanitizeErrorMessage(error: unknown, contentDirectory: string): string;
+export declare function errorPath(error: unknown): string | undefined;

package/dist/src/file_system_content_migration_types.d.ts

@@ -0,0 +1,99 @@
+import type { ContentMigrationBatch, ContentMigrationDiagnostic, ContentMigrationListEntry, ContentMigrationRegistry, ContentMigrationStatus, ContentMutationOperation, ContentSource, ResolvedRiebeckiteConfig, RiebeckitePlugin } from "@riebeckite/core";
+export type FutureContentSource = ContentSource & {
+    readonly changes: ReadonlyMap<string, Uint8Array | null>;
+};
+export type ContentMigrationPlanFile = {
+    readonly path: string;
+    readonly beforeFingerprint: string | null;
+    readonly afterFingerprint: string | null;
+};
+export type ContentMigrationVerification = {
+    readonly beforeFiles: number;
+    readonly afterFiles: number;
+    readonly beforePublicationFingerprint: string;
+    readonly afterPublicationFingerprint: string;
+    readonly derivedViews: number;
+};
+export type ContentMigrationPlan = {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly createdAt: string;
+    readonly migrations: readonly {
+        readonly id: string;
+        readonly version: number;
+        readonly fingerprint: string;
+    }[];
+    readonly baseContentFingerprint: string;
+    readonly mutationPlanId: string;
+    readonly mutationPlanFingerprint: string;
+    readonly planFingerprint: string;
+    readonly operations: readonly ContentMutationOperation[];
+    readonly changes: readonly ContentMigrationPlanFile[];
+    readonly diagnostics: readonly ContentMigrationDiagnostic[];
+    readonly conflicts: readonly ContentMigrationDiagnostic[];
+    readonly selections: ContentMigrationBatch["selections"];
+    readonly skipped: ContentMigrationBatch["skipped"];
+    readonly impact: ContentMigrationBatch["impact"];
+    readonly verification: ContentMigrationVerification;
+};
+export type FileSystemContentMigrationOptions = {
+    readonly contentDirectory: string;
+    readonly registry: ContentMigrationRegistry;
+    readonly config?: ResolvedRiebeckiteConfig;
+    readonly plugins?: readonly RiebeckitePlugin[];
+    readonly buildTime?: Date;
+    readonly exclude?: readonly string[];
+    readonly redirectField?: string;
+};
+export type ContentMigrationApplyOptions = {
+    readonly planPath?: string;
+    readonly ids?: readonly string[];
+};
+export type ContentMigrationApplyResult = {
+    readonly applied: boolean;
+    readonly skipped: boolean;
+    readonly plan: ContentMigrationPlan;
+    readonly journalPath?: string;
+    readonly changedPaths: readonly string[];
+    readonly conflicts: readonly ContentMigrationDiagnostic[];
+};
+export type ContentMigrationStatusEntry = {
+    readonly id: string;
+    readonly version: number;
+    readonly latestVersion?: number;
+    readonly status: ContentMigrationStatus;
+    readonly definitionMatches: boolean;
+    readonly planId?: string;
+    readonly appliedAt?: string;
+    readonly updatedAt: string;
+    readonly journal?: string;
+    readonly error?: string;
+};
+export type ContentMigrationStatusReport = {
+    readonly schemaVersion: 1;
+    readonly updatedAt: string;
+    readonly entries: readonly ContentMigrationStatusEntry[];
+    readonly migrations: readonly ContentMigrationListEntry[];
+    readonly historyCount: number;
+};
+export type ContentMigrationRecoverOptions = {
+    readonly journal?: string;
+    readonly migrationId?: string;
+};
+export type ContentMigrationRecoveryResult = {
+    readonly recovered: boolean;
+    readonly applied: boolean;
+    readonly skipped: boolean;
+    readonly restoredPaths: readonly string[];
+    readonly conflicts: readonly ContentMigrationDiagnostic[];
+};
+export type ContentMigrationRollbackOptions = {
+    readonly planId?: string;
+    readonly migrationId?: string;
+};
+export type ContentMigrationRollbackOutcome = {
+    readonly rolledBack: boolean;
+    readonly skipped: boolean;
+    readonly restoredPaths: readonly string[];
+    readonly conflicts: readonly ContentMigrationDiagnostic[];
+};

package/dist/src/file_system_content_mutation.d.ts

@@ -0,0 +1,25 @@
+import { type ContentMutationOperation, type ContentMutationPlan, type ContentMutationRecoveryResult, type ContentMutationResult, type ContentMutationRollbackResult } from "@riebeckite/core";
+export type FileSystemContentMutationOptions = {
+    readonly beforeWrite?: (path: string) => void | Promise<void>;
+    readonly beforeRecoveryRestore?: (path: string) => void | Promise<void>;
+    readonly afterRecoveryCapture?: (path: string) => void | Promise<void>;
+};
+export declare class FileSystemContentMutation {
+    private readonly contentDirectory;
+    private readonly options;
+    constructor(contentDirectory: string, options?: FileSystemContentMutationOptions);
+    plan(operations: readonly ContentMutationOperation[]): Promise<ContentMutationPlan>;
+    apply(plan: ContentMutationPlan): Promise<ContentMutationResult>;
+    recover(journalPath: string): Promise<ContentMutationRecoveryResult>;
+    rollback(journalPath: string): Promise<ContentMutationRollbackResult>;
+    private restoreChange;
+    savePlan(plan: ContentMutationPlan, planPath?: string): Promise<string>;
+    loadPlan(planPath: string): Promise<ContentMutationPlan>;
+    private revalidatePlan;
+    private planPath;
+    private root;
+    private loadFiles;
+    private verifyPreconditions;
+    private backup;
+    private acquireLock;
+}

package/dist/src/migration_state_store.d.ts

@@ -0,0 +1,9 @@
+import { type ContentMigrationHistory, type ContentMigrationState } from "@riebeckite/core";
+export declare function migrationStateDirectory(contentDirectory: string): string;
+export declare function migrationStatePath(contentDirectory: string): string;
+export declare function migrationHistoryPath(contentDirectory: string): string;
+export declare function migrationLockPath(contentDirectory: string): string;
+export declare function readMigrationState(contentDirectory: string): Promise<ContentMigrationState>;
+export declare function writeMigrationState(contentDirectory: string, state: ContentMigrationState): Promise<void>;
+export declare function readMigrationHistory(contentDirectory: string): Promise<ContentMigrationHistory>;
+export declare function writeMigrationHistory(contentDirectory: string, history: ContentMigrationHistory): Promise<void>;

package/dist/src/mutation_journal.d.ts

@@ -0,0 +1,33 @@
+import type { ContentMutationFileChange, ContentMutationPlan } from "@riebeckite/core";
+export type MutationJournal = {
+    readonly version: 1;
+    readonly id: string;
+    state: "prepared" | "applying" | "failed" | "complete" | "recovered" | "rolled-back";
+    readonly changes: readonly JournalChange[];
+};
+type StoredMutationPlan = {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly operations: unknown;
+    readonly changes: readonly StoredFileChange[];
+    readonly preconditions: ContentMutationPlan["preconditions"];
+    readonly warnings: ContentMutationPlan["warnings"];
+    readonly conflicts: ContentMutationPlan["conflicts"];
+};
+type StoredFileChange = Omit<ContentMutationFileChange, "content"> & {
+    readonly content: string | null;
+};
+export type JournalChange = {
+    readonly path: string;
+    readonly beforeFingerprint: string | null;
+    readonly afterFingerprint: string | null;
+    readonly backupPath?: string;
+    status: "pending" | "applied";
+};
+export declare function markApplied(journal: MutationJournal, filePath: string): void;
+export declare function parseJournal(value: string): MutationJournal;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function serializePlan(plan: ContentMutationPlan): StoredMutationPlan;
+export declare function parsePlan(value: string): ContentMutationPlan;
+export declare function samePlan(expected: ContentMutationPlan, actual: ContentMutationPlan): boolean;
+export {};

package/dist/src/path_helpers.d.ts

@@ -0,0 +1,2 @@
+export declare function isPathInsideDirectory(directory: string, file: string): boolean;
+export declare function toLogicalPath(directory: string, file: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/node",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,10 +23,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@riebeckite/core": "0.0.34"
+    "@riebeckite/core": "0.0.36",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@riebeckite/test": "0.0.34",
+    "@riebeckite/test": "0.0.36",
     "tsx": "^4.22.4"
   },
   "repository": {