dev: initial implementation of notebook-snapshot extension

Manual-commit notebook snapshot extension (JupyterLab 4): Backend - Storage adapter layer (Local + S3 via boto3, pip extra) - Dumb put/get/list/delete contract; key validation - S3Storage: lazy boto3 import, S3ConnectionError with friendly messages + connectivity check at startup - SnapshotStore - Strip code outputs/execution_count, MD5 on cleaned JSON - Gzipped envelope (id/timestamp/name/description/hash/size/notebook) - Append-only manifest.json (rebuildable from version files) - SnapshotUnchangedError when new hash matches most recent version - REST API (commit / list / content) under /snapshot/ namespace - traitlets config (storage_type, local_root, s3_* + S3_* env fallback) Frontend - snapshot:commit command (toolbar button + command palette) - Dialog for name + description - SnapshotPanel (left sidebar timeline) + DiffWidget (main area) - Cell diff: id-match first, LCS fallback; jsdiff for line diff - Restore via model.fromJSON() + context.save() (no refresh) - All AGENTS.md hard conventions enforced Tests: 33 backend pytest passing (storage + store + routes) Docs: AGENTS.md, design.md, README.md synced with implementation. Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-21 17:33:55 +08:00
commit cd1aba6698
67 changed files with 17926 additions and 0 deletions
@@ -0,0 +1,127 @@
+import * as React from 'react';
+import { ReactWidget } from '@jupyterlab/apputils';
+import { ServerConnection } from '@jupyterlab/services';
+
+import { getSnapshotContent } from '../api';
+import { INotebook } from '../diff';
+import { SnapshotModel } from '../model';
+import { CommandIDs } from '../commands';
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { INotebookTracker } from '@jupyterlab/notebook';
+
+function formatTimestamp(ts: number): string {
+  // timestamp is microseconds (see backend store.py)
+  const ms = ts / 1000;
+  return new Date(ms).toLocaleString();
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+interface PanelProps {
+  model: SnapshotModel;
+  app: JupyterFrontEnd;
+  tracker: INotebookTracker;
+  serverSettings: ServerConnection.ISettings;
+  onOpenDiff: (newNb: INotebook, oldNb: INotebook, name: string) => void;
+}
+
+const Panel: React.FC<PanelProps> = ({ model, app, tracker, serverSettings, onOpenDiff }) => {
+  const [, force] = React.useReducer(x => x + 1, 0);
+  React.useEffect(() => {
+    const onChange = () => force();
+    model.versionsChanged.connect(onChange);
+    return () => {
+      model.versionsChanged.disconnect(onChange);
+    };
+  }, [model]);
+
+  if (!model.path) {
+    return <div className="jp-snapshot-panel-empty">未选中 notebook</div>;
+  }
+  if (model.loading && model.versions.length === 0) {
+    return <div className="jp-snapshot-panel-empty">加载中…</div>;
+  }
+  if (model.versions.length === 0) {
+    return (
+      <div className="jp-snapshot-panel-empty">
+        <div>暂无快照</div>
+        <div className="jp-snapshot-panel-hint">点击工具栏「保存快照」按钮创建</div>
+      </div>
+    );
+  }
+  return (
+    <ul className="jp-snapshot-panel-list">
+      {model.versions.map(v => (
+        <li key={v.id} className="jp-snapshot-panel-item">
+          <div className="jp-snapshot-panel-item-header">
+            <span className="jp-snapshot-panel-name" title={v.name}>
+              {v.name}
+            </span>
+            <span className="jp-snapshot-panel-size">{formatSize(v.size)}</span>
+          </div>
+          {v.description ? (
+            <div className="jp-snapshot-panel-desc">{v.description}</div>
+          ) : null}
+          <div className="jp-snapshot-panel-time">{formatTimestamp(v.timestamp)}</div>
+          <div className="jp-snapshot-panel-actions">
+            <button
+              className="jp-snapshot-panel-button"
+              onClick={async () => {
+                const panel = tracker.currentWidget;
+                if (!panel) {
+                  return;
+                }
+                const notebookModel = panel.content.model;
+                if (!notebookModel) {
+                  return;
+                }
+                try {
+                  const oldNb = (await getSnapshotContent(
+                    serverSettings,
+                    model.path,
+                    v.id
+                  )) as INotebook;
+                  const newNb = notebookModel.toJSON() as unknown as INotebook;
+                  onOpenDiff(newNb, oldNb, v.name);
+                } catch (e) {
+                  console.error('Diff failed', e);
+                }
+              }}
+            >
+              对比
+            </button>
+            <button
+              className="jp-snapshot-panel-button"
+              onClick={() => {
+                void app.commands.execute(CommandIDs.restore, { id: v.id });
+              }}
+            >
+              恢复
+            </button>
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+};
+
+export class SnapshotPanel extends ReactWidget {
+  constructor(
+    private readonly _props: PanelProps
+  ) {
+    super();
+    this.addClass('jp-snapshot-panel');
+  }
+
+  render(): React.ReactElement {
+    return <Panel {...this._props} />;
+  }
+}