@qkix/strapi-plugin-rewind 0.1.0

package/dist/server/src/utils/captureContext.d.ts

@@ -0,0 +1,45 @@
+export type Origin = 'create' | 'update' | 'clone' | 'publish' | 'unpublish' | 'discardDraft' | 'restore';
+export interface SnapshotIntent {
+    uid: string;
+    relatedDocumentId: string;
+    locale: string | null;
+    origin: Origin;
+    /** Rows read before the action ran. Only `discardDraft` needs these. */
+    before: Record<string, unknown>[] | null;
+}
+/**
+ * Intents buffered against the transaction they belong to.
+ *
+ * Keyed by the Knex transaction object because that is the only thing the
+ * Content Manager's `update` and `publish` calls have in common — they are
+ * sequential siblings, not nested, so nothing about the call stack relates
+ * them. Strapi hands the same `trx` to every nested `db.transaction`, which
+ * makes it a reliable key, and a WeakMap means a finished transaction takes its
+ * buffer with it.
+ *
+ * Deliberately not an AsyncLocalStorage: commit callbacks run after the
+ * transaction resolves, outside whatever async context registered them, so a
+ * store looked up at flush time is always empty. The callback has to close over
+ * the buffer directly.
+ */
+interface TransactionBuffer {
+    intents: SnapshotIntent[];
+    flushRegistered: boolean;
+}
+export declare const bufferFor: (trx: object) => TransactionBuffer;
+/**
+ * Collapses intents that describe the same document and locale, keeping the one
+ * that best describes what the editor did.
+ */
+export declare const coalesce: (intents: SnapshotIntent[]) => SnapshotIntent[];
+/**
+ * Marks the current async context as a restore, so the write restore performs
+ * is not also recorded as an ordinary edit.
+ *
+ * An async-context flag is the right tool here and the wrong one for publish:
+ * `restore.apply()` calls the Document Service from inside its own call stack,
+ * so the write genuinely is nested. The Content Manager's publish is not.
+ */
+export declare const runAsRestore: <T>(fn: () => Promise<T>) => Promise<T>;
+export declare const isRestoreInProgress: () => boolean;
+export {};

package/dist/server/src/utils/persistTable.d.ts

@@ -0,0 +1,15 @@
+import type { Core } from '@strapi/strapi';
+/**
+ * Keeps the versions table alive when the plugin is not loaded.
+ *
+ * Strapi's schema sync drops any table it previously tracked that is no longer
+ * in the user schema. Disable this plugin for a single boot — to debug, to test
+ * an upgrade — and the history it exists to protect is gone without a prompt.
+ *
+ * `persisted_tables` is the core-store key `@strapi/database` consults before
+ * dropping (schema/diff.js). The EE `admin::persist-tables` service writes the
+ * same key, but it is registered only when `strapi.EE` is set, so it does not
+ * exist for the Community Edition users this plugin is for. Writing the key
+ * directly is a dozen lines and needs no EE code.
+ */
+export declare const persistVersionsTable: (strapi: Core.Strapi, tableName: string) => Promise<void>;

package/dist/server/src/utils/textDiff.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A word-level diff, and the text extraction that makes it useful.
+ *
+ * The alternative — reporting "content changed" — is true and worthless. The
+ * field an editor cares most about is usually rich text stored as JSON, so the
+ * readable part is pulled out and compared as prose. That is renderer-agnostic:
+ * it walks the structure collecting anything that reads as text, without
+ * knowing what a block is.
+ */
+export type DiffOp = 'equal' | 'added' | 'removed';
+export interface DiffSpan {
+    op: DiffOp;
+    value: string;
+}
+/**
+ * Above this, a full LCS table costs more memory and time than the answer is
+ * worth. The caller falls back to reporting that the field changed.
+ */
+export declare const MAX_DIFF_TOKENS = 2500;
+/**
+ * Longest common subsequence over words.
+ *
+ * Word-level rather than character-level because the output is read by a person
+ * deciding whether an edit was significant, and a character diff of prose is
+ * noise.
+ */
+export declare const diffWords: (before: string, after: string) => DiffSpan[];
+/**
+ * Pulls the human-readable text out of an arbitrary value.
+ *
+ * Rich text, components and dynamic zones are all nested objects and arrays
+ * whose shape this plugin deliberately does not model — a `text` key here, a
+ * `children` array there. Collecting every string reached is imprecise but
+ * stable across editors, and it is what turns "content changed" into a sentence
+ * an editor recognises.
+ */
+export declare const extractText: (value: unknown, depth?: number) => string;
+/** Collapses runs of whitespace so formatting-only edits do not read as changes. */
+export declare const normaliseText: (text: string) => string;
+/** Words of unchanged text kept either side of a change, for context. */
+export declare const CONTEXT_WORDS = 6;
+/**
+ * Drops the long stretches of unchanged text between changes.
+ *
+ * A one-word edit in a long article otherwise renders as the whole article with
+ * a single green word somewhere inside it, and the reader has to hunt for the
+ * thing the view exists to show. Unchanged runs are trimmed to a few words of
+ * context and marked with an ellipsis.
+ */
+export declare const collapseEqualSpans: (spans: DiffSpan[], contextWords?: number) => DiffSpan[];

package/dist/server/src/utils/thinning.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Deciding which versions to throw away.
+ *
+ * Kept as a pure function, and tested harder than anything else in the plugin,
+ * because it is the only code here that destroys data. Everything else can be
+ * wrong and merely unhelpful.
+ *
+ * The shape of the policy is "recent history in full, older history thinned":
+ * an editor looking at last week wants every save, and an editor looking at
+ * last year wants a handful of points, not four hundred.
+ */
+export interface RetentionPolicy {
+    /** Below this age nothing is touched. */
+    keepAllDays: number;
+    /** Up to this age, one version per calendar day survives. */
+    dailyUntilDays: number;
+    /** Older than that, one per ISO week survives. */
+    maxAgeDays: number;
+    /** Whether publish/unpublish/discardDraft/restore are exempt entirely. */
+    keepAnchors: boolean;
+}
+export declare const DEFAULT_POLICY: RetentionPolicy;
+export interface PrunableVersion {
+    id: number;
+    createdAt: string | Date;
+    origin: string;
+    pinned?: boolean | null;
+}
+/**
+ * Ids to delete, given every version of one document in one locale.
+ *
+ * Takes the whole set for a document rather than a page of rows: "the newest
+ * version that day" is not a question a single row can answer.
+ */
+export declare const selectExpendable: (versions: PrunableVersion[], now: Date, policy?: RetentionPolicy) => number[];

package/dist/server/src/utils/versionLabel.d.ts

@@ -0,0 +1,14 @@
+import type { Core } from '@strapi/strapi';
+/**
+ * Derives the short, human-readable stand-in shown for a version in the panel.
+ *
+ * Without it every row is a badge and a timestamp, so two versions holding
+ * completely different content look identical and nothing tells an editor what
+ * pressing Restore would give them.
+ *
+ * The field is whatever the Content Manager displays as the entry's title, so
+ * the panel agrees with the rest of the admin. The returned function caches the
+ * lookup per content type: a backfill runs it once per row, and the
+ * configuration behind it does not change while the server is up.
+ */
+export declare const createLabeller: (strapi: Core.Strapi) => (uid: string, data: Record<string, unknown> | null | undefined) => Promise<string | null>;

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@qkix/strapi-plugin-rewind",
+  "version": "0.1.0",
+  "description": "Document version history for Strapi v5 — snapshots on every save, with restore",
+  "strapi": {
+    "kind": "plugin",
+    "name": "rewind",
+    "displayName": "Rewind",
+    "description": "Document version history for Strapi v5 — snapshots on every save, with restore"
+  },
+  "keywords": [
+    "strapi",
+    "strapi-plugin",
+    "strapi-v5",
+    "history",
+    "versioning",
+    "versions",
+    "revisions",
+    "audit",
+    "restore",
+    "cms",
+    "headless-cms"
+  ],
+  "type": "commonjs",
+  "exports": {
+    "./package.json": "./package.json",
+    "./strapi-admin": {
+      "types": "./dist/admin/src/index.d.ts",
+      "source": "./admin/src/index.ts",
+      "import": "./dist/admin/index.mjs",
+      "require": "./dist/admin/index.js",
+      "default": "./dist/admin/index.js"
+    },
+    "./strapi-server": {
+      "types": "./dist/server/src/index.d.ts",
+      "source": "./server/src/index.ts",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@strapi/sdk-plugin": "^5.3.2",
+    "@strapi/strapi": "^5.12.5",
+    "@strapi/typescript-utils": "^5.12.5",
+    "@types/react": "^18.3.8",
+    "@types/react-dom": "^18.3.0",
+    "eslint": "^10.8.1",
+    "prettier": "^3.5.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "styled-components": "^6.1.17",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@qkix/eslint-config": "0.0.0",
+    "@qkix/strapi-test-harness": "0.0.0",
+    "@qkix/tsconfig": "0.0.0"
+  },
+  "peerDependencies": {
+    "@strapi/admin": "^5.0.0",
+    "@strapi/design-system": "^2.0.0",
+    "@strapi/icons": "^2.0.0",
+    "@strapi/strapi": "^5.0.0",
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0",
+    "react-intl": "^6.0.0 || ^7.0.0",
+    "styled-components": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0 <=24.x.x",
+    "npm": ">=6.0.0"
+  },
+  "license": "MIT",
+  "author": "qkix",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qkix/strapi-plugins.git",
+    "directory": "packages/strapi-plugin-rewind"
+  },
+  "bugs": {
+    "url": "https://github.com/qkix/strapi-plugins/issues"
+  },
+  "homepage": "https://github.com/qkix/strapi-plugins#readme",
+  "nx": {
+    "tags": [
+      "scope:plugin"
+    ],
+    "targets": {
+      "test": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && strapi-plugin build --minify",
+    "clean": "rm -rf dist",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "strapi-plugin verify",
+    "watch": "strapi-plugin watch",
+    "watch:link": "strapi-plugin watch:link",
+    "typecheck": "tsc -p admin/tsconfig.json --noEmit && tsc -p server/tsconfig.json --noEmit"
+  }
+}