cosmos-explorer/docs/remove-notebooks-plan.md

Implementation Plan: Remove Phoenix & Notebooks

Problem statement

Cosmos Explorer contains a large, deeply-integrated notebooks feature backed by the Phoenix compute-container service and the Juno service, plus a GitHub integration used to pin/browse notebook repositories. This functionality is being retired. The goal is to remove all notebooks/Phoenix/Juno/GitHub-for-notebooks code, dependencies, UI surfaces, telemetry, and configuration, while preserving the database shell terminals (Mongo / Cassandra / Postgres / VCoreMongo), which today share the Terminal infrastructure with notebooks.

This document is the implementation plan only. No code changes are made here.

Scope decisions (confirmed)

• Database shells: Keep the Mongo/Cassandra/Postgres/VCoreMongo shells, but migrate them to use the CloudShell path exclusively. Remove the legacy Phoenix notebook-server shell path.
• GitHub integration: Remove entirely (it exists only for notebook pinned repos).
• Schema Analyzer (src/Explorer/Notebook/SchemaAnalyzer): Remove.
• Phasing: Every phase must leave the app in a buildable, shippable state (build + lint + strict compile + unit tests green; shells still work).
• Localization: Remove notebook/GitHub strings from all resource files — src/Localization/en/Resources.json and every non-English locale (src/Localization/<locale>/Resources.json). (This deletion is an exception to the usual convention of editing only the English file.)

Prior art / related commits

This is a continuation of an in-progress removal effort. Reference commits:

• 7295d63a — Remove gallery.html and all associated gallery functionality (#2474)
• a36467f4 — Remove Phoenix getDbAccountAllowedStatus; isPhoenixNotebooks/ isPhoenixFeatures now always false (#2472)
• 31385950 — removed NotebookViewer file (#2281)

Note: An unmerged branch users/jawelton/remove-notebooks-terminal-052126 already contains related work (5989c77c "Remove terminal.html webpack entry point and notebooks terminal code", c7f9d7e3 "Switch VCore Mongo quickstart to use CloudShell terminal"). These are not in master. Reconcile with that branch before/while starting Phase 1 to avoid duplicate or conflicting work.

Current-state survey (what exists today)

Core directories / files

• src/Phoenix/PhoenixClient.ts — container allocation, heartbeat, status polling.
• src/Juno/JunoClient.ts (+ test) — pinned-repo / notebook metadata service client.
• src/Explorer/Notebook/ — the bulk of the feature:
  • useNotebook.ts (Zustand store), NotebookManager.tsx, NotebookContentClient.ts, NotebookClientV2.ts, NotebookContainerClient.ts, NotebookContentItem.ts, NotebookUtil.ts, NTeractUtil.ts, FileSystemUtil.ts
  • NotebookComponent/ (nteract redux store, epics, reducers, content providers)
  • NotebookRenderer/ (nteract cell rendering, decorators, outputs)
  • SchemaAnalyzer/, SecurityWarningBar/
• src/Explorer/Controls/Notebook/NotebookTerminalComponent.tsx (+ less/test)
• src/Explorer/Controls/NotebookViewer/ — read-only viewer + metadata.
• src/Explorer/Tabs/NotebookV2Tab.ts, NotebookTabBase.ts, SchemaAnalyzerTab.ts
• src/Explorer/Panes/CopyNotebookPane/
• src/Explorer/Tabs/ShellAdapters/NotebookTerminalComponentAdapter.tsx
• src/CellOutputViewer/ — webpack entry cellOutputViewer.
• src/Utils/NotebookConfigurationUtils.ts, src/hooks/useNotebookSnapshotStore.ts
• src/Utils/arm/generatedClients/cosmosNotebooks/ — generated ARM client.

GitHub integration (notebook-only)

• src/GitHub/ (GitHubClient.ts, GitHubContentProvider.ts, GitHubOAuthService.ts, GitHubConnector.ts), src/Utils/GitHubUtils.ts
• src/Explorer/Controls/GitHub/ (AuthorizeAccess, AddRepo, GitHubRepos components)
• src/Explorer/Panes/GitHubReposPanel/
• webpack entry connectToGitHub + src/connectToGitHub.html

Integration / glue points (edited, not deleted)

• src/Explorer/Explorer.tsx — phoenixClient, notebookManager, gitHubOAuthService, initNotebooks, initiateAndRefreshNotebookList, allocateContainer, openNotebook*, openNotebookTerminal, createNotebookContentItemFile, etc.
• src/Explorer/Menus/CommandBar/CommandBarComponentButtonFactory.tsx (+ adapter, test) — New Notebook / Open Terminal / shell buttons branching on isShellEnabled.
• src/Explorer/Tree/treeNodeUtil.tsx / ResourceTreeAdapter.tsx / ResourceTree.tsx — "My Notebooks" / "GitHub" tree nodes; isNotebookEnabled plumbing.
• src/Explorer/SplashScreen/SplashScreen.tsx — notebook cards + openNotebookTerminal for Postgres/VCoreMongo shells.
• src/Explorer/Tabs/TerminalTab.tsx — chooses CloudShell vs notebook-server adapter.
• src/Explorer/OpenActions/OpenActions.tsx, src/Explorer/ContextMenuButtonFactory.tsx, src/Explorer/Tree/Collection.ts, src/Explorer/useSelectedNode.ts, src/Explorer/MostRecentActivity/MostRecentActivity.ts
• src/hooks/useKnockoutExplorer.ts, src/hooks/useTabs.ts
• src/ConfigContext.ts, src/Common/Constants.ts, src/Contracts/DataModels.ts, src/Contracts/ViewModels.ts, src/Contracts/ActionContracts.ts, src/Platform/Hosted/extractFeatures.ts (+ test)
• src/Shared/Telemetry/TelemetryConstants.ts
• src/Localization/en/Resources.json and all non-English src/Localization/<locale>/Resources.json
• webpack.config.js — cellOutputViewer, connectToGitHub entries + HTML plugins.
• package.json — @nteract/*, @jupyterlab/*, @phosphor/widgets, rx-jupyter, and other notebook-only dependencies.

Critical coupling — Terminal / shells

• TerminalTab uses CloudShellTerminalComponentAdapter when userContext.features.enableCloudShell, otherwise NotebookTerminalComponentAdapter (which needs a Phoenix-allocated notebook server + terminal.html iframe).
• Command-bar/splash shell buttons branch on useNotebook.getState().isShellEnabled || userContext.features.enableCloudShell.
• Explorer.openNotebookTerminal(...) is the shared entry for opening shells and must be retained (and rewired to CloudShell-only) — only its notebook-server behavior is removed.

Phased approach

Each phase is independently buildable and shippable. Within each phase, all references to removed code are also removed so the tree compiles. After every phase run: npm run compile, npm run compile:strict, npm run lint, npm run format:check, npm test, and a webpack build (npm run build:ci); manually verify the four shells still open.

Phase 1 — Decouple database shells to CloudShell-only

Remove the legacy Phoenix notebook-server terminal path so shells no longer depend on notebook provisioning.

• Rewire TerminalTab to always use CloudShellTerminalComponentAdapter; delete the NotebookTerminalComponentAdapter branch and getNotebookServerInfo.
• Delete src/Explorer/Tabs/ShellAdapters/NotebookTerminalComponentAdapter.tsx and src/Explorer/Controls/Notebook/NotebookTerminalComponent.tsx (+ less/test/snapshot).
• Simplify shell buttons in CommandBarComponentButtonFactory and SplashScreen to drop the isShellEnabled branch (CloudShell path only); keep openNotebookTerminal.
• Verify whether the terminal/terminal.html webpack entry is still needed by CloudShell. If unused, remove it and src/Terminal/; otherwise keep.
• Outcome: Shells run purely on CloudShell. Phoenix no longer needed for terminals.

Phase 2 — Remove the in-app notebook authoring & rendering experience

Delete the notebook tabs, the nteract rendering engine, panes, and the read-only viewer, and remove all UI entry points that open notebooks.

• Delete: src/Explorer/Notebook/NotebookComponent/, src/Explorer/Notebook/NotebookRenderer/, src/Explorer/Notebook/SecurityWarningBar/, NotebookClientV2.ts, notebookClientV2.test.ts, NotebookContentClient.ts, NTeractUtil.ts, NotebookContentItem.ts, NotebookUtil.ts (+ test), FileSystemUtil.ts.
• Delete tabs/panes/viewer: src/Explorer/Tabs/NotebookV2Tab.ts, NotebookTabBase.ts, src/Explorer/Panes/CopyNotebookPane/, src/Explorer/Controls/NotebookViewer/, src/CellOutputViewer/ (+ cellOutputViewer webpack entry & HTML plugin).
• Remove notebook entry points: "New Notebook"/open-notebook buttons in CommandBarComponentButtonFactory (+ test), OpenActions.tsx, ContextMenuButtonFactory.tsx, splash-screen notebook cards & recent-notebook items (MostRecentActivity OpenNotebook type), and the openNotebook* / createNotebookContentItemFile methods on Explorer.
• Remove notebook deps from package.json: @nteract/*, @jupyterlab/*, @phosphor/widgets, rx-jupyter (and any now-unused transitive notebook-only libs).
• Outcome: Notebooks can no longer be authored, opened, or rendered.

Phase 3 — Remove Schema Analyzer

• Delete src/Explorer/Notebook/SchemaAnalyzer/ and src/Explorer/Tabs/SchemaAnalyzerTab.ts.
• Remove Schema Analyzer command-bar button and any tree/menu entry points.

Phase 4 — Remove GitHub integration

• Delete src/GitHub/, src/Explorer/Controls/GitHub/, src/Explorer/Panes/GitHubReposPanel/, src/Utils/GitHubUtils.ts, src/connectToGitHub.html, and the connectToGitHub webpack entry & HTML plugin.
• Remove gitHubOAuthService, GitHub pinned-repo wiring, and gitHubNotebooksContentRoot usage from Explorer.tsx, useNotebook.ts, NotebookManager.tsx, and JunoClient pinned-repo methods.
• Remove GitHub-related localization keys from all locale files (en + non-English).

Phase 5 — Remove Phoenix and the notebook container/allocation core

• Delete src/Phoenix/, src/Explorer/Notebook/NotebookContainerClient.ts, src/Explorer/Notebook/NotebookManager.tsx, src/Explorer/Notebook/useNotebook.ts, src/Utils/NotebookConfigurationUtils.ts, src/hooks/useNotebookSnapshotStore.ts.
• Remove from Explorer.tsx: phoenixClient, notebookManager, _isInitializingNotebooks, initNotebooks, initiateAndRefreshNotebookList, refreshNotebookList, allocateContainer, container heartbeat/connection logic, and notebook-server URL feature overrides.
• Remove notebook tree nodes ("My Notebooks") and isNotebookEnabled plumbing from treeNodeUtil.tsx, ResourceTreeAdapter.tsx, ResourceTree.tsx, Collection.ts, useSelectedNode.ts (+ update tree snapshots/tests).
• Remove notebook initialization from useKnockoutExplorer.ts and notebook tab handling in useTabs.ts.

Phase 6 — Remove residual clients, config, contracts, telemetry & strings

• Delete src/Juno/ and src/Utils/arm/generatedClients/cosmosNotebooks/.
• Remove notebook fields from ConfigContext.ts, Constants.ts (Notebook namespace), DataModels.ts (notebook/Phoenix/container interfaces), ViewModels.ts, ActionContracts.ts, and notebook feature flags from extractFeatures.ts (+ update test).
• Remove notebook/Phoenix telemetry actions/areas from TelemetryConstants.ts (preserve enum numbering if other systems depend on it — mirror the cautious approach in a36467f4).
• Remove remaining notebook strings from all locale Resources.json files (en + every non-English locale) and any notebook images (e.g. images/notebook/).
• Final full build + test sweep; update EndpointUtils.ts (allowedNotebookServerUrls) and any docs/comments referencing notebooks.

Cross-cutting verification (run after each phase)

npm run compile
npm run compile:strict
npm run lint
npm run format:check
npm test
npm run build:ci

Plus manual smoke test: open Mongo, Cassandra, Postgres, and VCoreMongo shells.

Notes & considerations

• Strict null checks: any file edited may need to stay in / be removed from tsconfig.strict.json. Remove deleted files from that list.
• Snapshots: several Jest snapshots reference notebook UI (treeNodeUtil, SettingsComponent, panel snapshots). Regenerate after edits.
• Telemetry enum safety: prior commit a36467f4 deliberately reverted removal of enum values to avoid breaking downstream consumers. Prefer leaving enum numeric values intact unless confirmed safe to remove.
• enableCloudShell feature flag: confirm it is enabled in all target environments before removing the Phoenix shell fallback, or shells will break.
• E2E tests: check test/ for notebook/terminal specs to update or remove; shells may have E2E coverage that needs the CloudShell-only path.
• Reconcile with branch users/jawelton/remove-notebooks-terminal-052126 to avoid rework, especially in Phase 1.