@plmbr/notebook-intelligence 5.0.0

package/lib/tour/tour-state.js

@@ -0,0 +1,81 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+/**
+ * localStorage-backed persistence for the first-run tour.
+ *
+ * The tour is shown exactly once per browser per major tour version. The
+ * version is bumped (in code) whenever the step set changes meaningfully
+ * so existing users get re-prompted instead of silently missing new
+ * onboarding content. Users can also re-run the tour on demand via the
+ * `notebook-intelligence:show-tour` command, which calls `resetTour()`.
+ *
+ * Why localStorage and not server-side state: the tour is purely UI; a
+ * round trip to the Jupyter server on every sidebar mount just to check
+ * a single flag would add latency to a hot path. localStorage is
+ * per-browser, which is the right granularity (a user signing in on a
+ * second browser benefits from seeing the tour again).
+ */
+// Bump when the tour's step set changes meaningfully enough to want
+// existing users to re-see it. Keys older than the current version are
+// ignored, and writes always use the current version.
+export const TOUR_VERSION = 1;
+// Exported so tests can clear the same key the production code writes,
+// instead of duplicating the string literal.
+export const TOUR_STORAGE_KEY = 'nbi.tour.completed';
+const TOUR_KEY = TOUR_STORAGE_KEY;
+function safeStorage() {
+    // localStorage can throw under some sandboxed iframe / privacy modes;
+    // a thrown access here would crash the sidebar mount. Treat absence
+    // as "tour was never completed" rather than failing closed.
+    try {
+        return typeof window !== 'undefined' ? window.localStorage : null;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+export function hasCompletedTour() {
+    const storage = safeStorage();
+    if (!storage) {
+        return false;
+    }
+    const raw = storage.getItem(TOUR_KEY);
+    if (!raw) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return (parsed === null || parsed === void 0 ? void 0 : parsed.version) === TOUR_VERSION;
+    }
+    catch (_a) {
+        // Stale / corrupt entry from an older NBI version. Treat as not
+        // completed; the next markCompleted will overwrite with the current
+        // shape.
+        return false;
+    }
+}
+export function markTourCompleted() {
+    const storage = safeStorage();
+    if (!storage) {
+        return;
+    }
+    try {
+        storage.setItem(TOUR_KEY, JSON.stringify({ version: TOUR_VERSION }));
+    }
+    catch (_a) {
+        // Quota exceeded / private mode rejecting writes. Worst case the
+        // tour fires again on the next sidebar mount, which is preferable
+        // to crashing the sidebar.
+    }
+}
+export function resetTour() {
+    const storage = safeStorage();
+    if (!storage) {
+        return;
+    }
+    try {
+        storage.removeItem(TOUR_KEY);
+    }
+    catch (_a) {
+        // See markTourCompleted.
+    }
+}

package/lib/tour/tour-steps.d.ts

@@ -0,0 +1,33 @@
+export type TourPlacement = 'top' | 'bottom' | 'left' | 'right' | 'center';
+export interface ITourStep {
+    id: string;
+    title: string;
+    description: string | (() => string);
+    anchorId: string | null;
+    placement: TourPlacement;
+    requires?: () => boolean;
+}
+interface IDefaultsSchema {
+    command?: {
+        label?: string;
+    };
+    ui?: {
+        skip?: string;
+        next?: string;
+        back?: string;
+        done?: string;
+    };
+    steps?: Record<string, {
+        title?: string;
+        description?: string;
+        description_singular?: string;
+        description_plural?: string;
+    }>;
+}
+export declare const TOUR_DEFAULTS: IDefaultsSchema;
+export declare const ALL_TOUR_STEPS: readonly ITourStep[];
+export type IResolvedTourStep = Omit<ITourStep, 'description'> & {
+    description: string;
+};
+export declare function activeTourSteps(): IResolvedTourStep[];
+export {};

package/lib/tour/tour-steps.js

@@ -0,0 +1,216 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+/**
+ * Step definitions for the first-run tour.
+ *
+ * The copy (titles, descriptions, button labels, command palette
+ * label) lives in `tour-defaults.json`, which uses the same schema as
+ * an admin override file (see `docs/admin-tour-config.md`). The
+ * structural wiring (DOM anchor ids, placements, capability gates)
+ * lives in TypeScript because it isn't user-facing copy.
+ *
+ * Each step anchors to a DOM element by `data-tour-id` (added on the
+ * matching React element). Using a dedicated attribute rather than a
+ * CSS class makes the contract explicit and decouples the tour from
+ * styling changes.
+ *
+ * The `requires` predicate filters out steps that don't apply to the
+ * current deployment (e.g. the Claude history step is skipped when
+ * Claude CLI is not installed). Predicates close over the snapshot of
+ * capabilities at tour start, so a CLI being installed mid-tour does
+ * not retroactively insert a step.
+ */
+import { NBIAPI } from '../api';
+import { applyTourOverrides, launcherTileTemplates } from './tour-config';
+import { TOUR_ANCHOR } from './tour-anchors';
+import defaultsJson from './tour-defaults.json';
+// Bundled defaults file. Same schema as an admin override; the
+// override applier overlays the admin layer on top of these.
+export const TOUR_DEFAULTS = defaultsJson;
+function defaultText(stepId, key) {
+    var _a;
+    const step = (_a = TOUR_DEFAULTS.steps) === null || _a === void 0 ? void 0 : _a[stepId];
+    const value = step === null || step === void 0 ? void 0 : step[key];
+    return typeof value === 'string' ? value : '';
+}
+// Map every Coding Agent launcher id to (a) the capability flag that
+// decides whether the tile shows up at all and (b) the display name
+// the tour should use. Order matches what users see in the JL
+// Launcher.
+const CODING_AGENT_LAUNCHERS = [
+    {
+        id: 'claude-code',
+        label: 'Claude Code',
+        available: () => NBIAPI.config.isClaudeCliAvailable
+    },
+    {
+        id: 'codex',
+        label: 'Codex',
+        available: () => NBIAPI.config.isCodexCliAvailable
+    },
+    {
+        id: 'opencode',
+        label: 'opencode',
+        available: () => NBIAPI.config.isOpenCodeCliAvailable
+    },
+    {
+        id: 'pi',
+        label: 'Pi',
+        available: () => NBIAPI.config.isPiCliAvailable
+    },
+    {
+        id: 'github-copilot-cli',
+        label: 'GitHub Copilot CLI',
+        available: () => NBIAPI.config.isGitHubCopilotCliAvailable
+    }
+];
+function visibleCodingAgentLaunchers() {
+    return CODING_AGENT_LAUNCHERS.filter(l => l.available() &&
+        !NBIAPI.config.isCodingAgentLauncherDisabledByPolicy(l.id)).map(l => l.label);
+}
+function formatLauncherList(names) {
+    if (names.length === 0) {
+        return '';
+    }
+    if (names.length === 1) {
+        return names[0];
+    }
+    if (names.length === 2) {
+        return `${names[0]} and ${names[1]}`;
+    }
+    return `${names.slice(0, -1).join(', ')}, and ${names[names.length - 1]}`;
+}
+function launcherTilesDescription() {
+    var _a, _b, _c;
+    const names = visibleCodingAgentLaunchers();
+    const list = formatLauncherList(names);
+    // Admin overrides win; defaults supply the fallback templates.
+    const overrideTemplates = launcherTileTemplates(NBIAPI.config.tourOverrides);
+    const defaultStep = (_a = TOUR_DEFAULTS.steps) === null || _a === void 0 ? void 0 : _a['launcher-tiles'];
+    const template = names.length === 1
+        ? ((_b = overrideTemplates.singular) !== null && _b !== void 0 ? _b : defaultStep === null || defaultStep === void 0 ? void 0 : defaultStep.description_singular)
+        : ((_c = overrideTemplates.plural) !== null && _c !== void 0 ? _c : defaultStep === null || defaultStep === void 0 ? void 0 : defaultStep.description_plural);
+    return template ? template.replace(/\{launchers\}/g, list) : '';
+}
+export const ALL_TOUR_STEPS = Object.freeze([
+    {
+        id: 'welcome',
+        title: defaultText('welcome', 'title'),
+        description: defaultText('welcome', 'description'),
+        anchorId: null,
+        placement: 'center'
+    },
+    {
+        id: 'new-chat',
+        title: defaultText('new-chat', 'title'),
+        description: defaultText('new-chat', 'description'),
+        anchorId: TOUR_ANCHOR.newChat,
+        placement: 'bottom',
+        // The + button is only rendered in Claude mode (it restarts the
+        // Claude client). Skip when not in Claude mode so the tour doesn't
+        // describe a missing affordance.
+        requires: () => NBIAPI.config.isInClaudeCodeMode
+    },
+    {
+        id: 'claude-history',
+        title: defaultText('claude-history', 'title'),
+        description: defaultText('claude-history', 'description'),
+        anchorId: TOUR_ANCHOR.claudeHistory,
+        placement: 'bottom',
+        // Visible only when Claude CLI is available AND Claude mode is on.
+        // Without the second guard the anchor isn't even rendered, so the
+        // tour would silently skip; the `requires` keeps the skip
+        // explicit.
+        requires: () => NBIAPI.config.isClaudeCliAvailable && NBIAPI.config.isInClaudeCodeMode
+    },
+    {
+        id: 'settings-gear',
+        title: defaultText('settings-gear', 'title'),
+        description: defaultText('settings-gear', 'description'),
+        anchorId: TOUR_ANCHOR.settingsGear,
+        placement: 'bottom'
+    },
+    {
+        id: 'slash-commands',
+        title: defaultText('slash-commands', 'title'),
+        description: defaultText('slash-commands', 'description'),
+        anchorId: TOUR_ANCHOR.slashCommands,
+        placement: 'top'
+    },
+    {
+        id: 'add-context',
+        title: defaultText('add-context', 'title'),
+        description: defaultText('add-context', 'description'),
+        anchorId: TOUR_ANCHOR.addContext,
+        placement: 'top'
+    },
+    {
+        id: 'upload-file',
+        title: defaultText('upload-file', 'title'),
+        description: defaultText('upload-file', 'description'),
+        anchorId: TOUR_ANCHOR.uploadFile,
+        placement: 'top'
+    },
+    {
+        id: 'drag-and-drop',
+        title: defaultText('drag-and-drop', 'title'),
+        description: defaultText('drag-and-drop', 'description'),
+        anchorId: TOUR_ANCHOR.promptInput,
+        placement: 'top'
+    },
+    {
+        id: 'chat-mode',
+        title: defaultText('chat-mode', 'title'),
+        description: defaultText('chat-mode', 'description'),
+        anchorId: TOUR_ANCHOR.chatMode,
+        placement: 'top',
+        // Mode picker is hidden in Claude mode (Claude owns its own loop).
+        requires: () => !NBIAPI.config.isInClaudeCodeMode
+    },
+    {
+        id: 'launcher-tiles',
+        title: defaultText('launcher-tiles', 'title'),
+        // Dynamic description so the step only mentions the CLI tools the
+        // user actually has installed. Skipped entirely when zero are
+        // available (see the requires predicate below). Both the default
+        // templates and admin overrides flow through this thunk so the
+        // {launchers} placeholder gets substituted with the same
+        // comma-joined list either way.
+        description: launcherTilesDescription,
+        anchorId: null,
+        placement: 'center',
+        // Skip the step on machines where no coding-agent CLI is installed
+        // (or admin policy hides every tile) so the tour doesn't promise an
+        // affordance the user can't reach.
+        requires: () => visibleCodingAgentLaunchers().length > 0
+    },
+    {
+        id: 'done',
+        title: defaultText('done', 'title'),
+        description: defaultText('done', 'description'),
+        anchorId: null,
+        placement: 'center'
+    }
+]);
+export function activeTourSteps() {
+    // Pipeline:
+    //   1. Apply admin overrides (title/description rewrites, per-step
+    //      enabled:false drops). The default-overrides path returns a
+    //      shallow copy so the rest of the pipeline doesn't mutate the
+    //      ALL_TOUR_STEPS module-level constant.
+    //   2. Filter on the per-step `requires()` predicate (capability /
+    //      mode gates).
+    //   3. Resolve any thunk descriptions to plain strings so the
+    //      overlay can render them directly. Doing this here (rather
+    //      than at render time) matches the "snapshot on mount"
+    //      semantics: a capability change mid-tour doesn't reshape step
+    //      copy under the user.
+    const overrides = NBIAPI.config.tourOverrides;
+    return applyTourOverrides(ALL_TOUR_STEPS, overrides)
+        .filter(step => (step.requires ? step.requires() : true))
+        .map(step => ({
+        ...step,
+        description: typeof step.description === 'function'
+            ? step.description()
+            : step.description
+    }));
+}

package/lib/utils.d.ts

@@ -0,0 +1,53 @@
+import { CodeCell } from '@jupyterlab/cells';
+import { CodeEditor } from '@jupyterlab/codeeditor';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { NotebookPanel } from '@jupyterlab/notebook';
+import { shellSingleQuote } from './shell-utils';
+export declare function removeAnsiChars(str: string): string;
+export declare function waitForDuration(duration: number): Promise<void>;
+export declare function moveCodeSectionBoundaryMarkersToNewLine(source: string): string;
+export declare function extractLLMGeneratedCode(code: string): string;
+export declare function isDarkTheme(): boolean;
+export declare function markdownToComment(source: string): string;
+export declare function formatJupyterError(output: any): string;
+export declare function cellOutputHasError(cell: CodeCell): boolean;
+export declare function cellOutputAsText(cell: CodeCell): string;
+export declare function joinMultilineString(value: unknown): string;
+export declare function getTokenCount(source: string): number;
+export declare function truncateToTokenCount(text: string, maxTokens: number): {
+    text: string;
+    size: number;
+    truncated: boolean;
+};
+export declare function compareSelectionPoints(lhs: CodeEditor.IPosition, rhs: CodeEditor.IPosition): boolean;
+export declare function compareSelections(lhs: CodeEditor.IRange, rhs: CodeEditor.IRange): boolean;
+export declare function isSelectionEmpty(selection: CodeEditor.IRange): boolean;
+export declare function getSelectionInEditor(editor: CodeEditor.IEditor): string;
+export declare function getWholeNotebookContent(np: NotebookPanel): string;
+export declare function applyCodeToSelectionInEditor(editor: CodeEditor.IEditor, code: string): void;
+export { shellSingleQuote };
+/**
+ * Return `uri` if its scheme is in the chat-anchor allowlist, else null.
+ * Mirrors the server-side `safe_anchor_uri` check so that anchor parts
+ * coming from arbitrary LLM/tool output cannot render `javascript:`,
+ * `data:`, `vbscript:`, `blob:`, or other dangerous schemes through React's
+ * `href` attribute. The server applies the same filter at emit time; this
+ * is defense in depth for stream replays, persisted history, and any path
+ * that injects anchor parts directly into the React tree.
+ */
+export declare function safeAnchorUri(uri: string | undefined | null): string | null;
+/**
+ * Build a `claude --resume <id>` command wrapped in `cd <cwd>` so the
+ * resulting one-liner works from any terminal. `claude --resume` is
+ * cwd-scoped — it looks up the transcript under the encoded form of the
+ * user's CURRENT shell cwd — so the bare id alone only works when the
+ * user happens to be in the JupyterLab working directory.
+ */
+export declare function buildResumeCommand(cwd: string, sessionId: string): string;
+/**
+ * Write `text` to the system clipboard. Falls back to a hidden textarea +
+ * `document.execCommand('copy')` when the async Clipboard API is unavailable
+ * or rejects (e.g. missing permission, insecure context).
+ */
+export declare function writeTextToClipboard(text: string): Promise<boolean>;
+export declare function chooseWorkspaceDirectory(docManager: IDocumentManager, label: string, defaultPath?: string): Promise<string | undefined>;