fix(tour): run guided-tour orchestration once on every boot

The Phoenix onboarding tour and the newly-added-features markdown were
both wired up in ways that left users in non-default native projects
silently un-onboarded. Two specific gaps:

- new-project.js only called guidedTour.startTourIfNeeded() from
  closeDialogue() (fires when the new-project dialog is opened and
  then dismissed via openFolder) and from init() when the welcome
  screen pref was off. On a native app with a non-default project
  open, _shouldNotShowDialog() returned true and the dialog was
  never shown, so startTourIfNeeded() was never reached and the
  tour could not fire on any subsequent boot either.
- newly-added-features.init() was called directly from main.js
  regardless of project context, so the "what's new" markdown
  could open under a user's current project tabs instead of the
  welcome project.

Move all post-boot orchestration to guided-tour.js, fire it from a
single _bootDonePromise.then() in new-project.js, and gate the
"newly added features" surfacing on a real higher-version change
(detected via semver vs the new userAlreadyDidAction.lastSeenAppVersion).
On a higher version we switch to the welcome project first so the
markdown lands in the onboarding context. Downgrades are a no-op and
leave state untouched so a future re-upgrade to a previously-seen
version does not re-fire. PhoenixTour stays a once-per-lifetime
overlay tour gated by its own CURRENT_TOUR_VERSION constant.

Author: abose

src/extensionsIntegrated/Phoenix/guided-tour.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright (c) 2021 - present core.ai. All rights reserved.
 
-/*global logger*/
+/*global logger, jsPromise*/
 
 define(function (require, exports, module) {
     const KernalModeTrust = window.KernalModeTrust;
@@ -21,9 +21,80 @@ define(function (require, exports, module) {
         Mustache = require("thirdparty/mustache/mustache"),
         SurveyTemplate = require("text!./html/survey-template.html"),
         PhoenixTour = require("./phoenix-tour"),
+        newFeature = require("./newly-added-features"),
+        ProjectManager = require("project/ProjectManager"),
+        semver = require("thirdparty/semver.browser"),
         NOTIFICATION_BACKOFF = 10000,
         GUIDED_TOUR_LOCAL_STORAGE_KEY = "guidedTourActions";
 
+    function _currentAppVersion() {
+        return window.AppConfig && window.AppConfig.apiVersion;
+    }
+
+    function _isNewerVersion(v1, v2) {
+        try {
+            return semver.gt(v1, v2);
+        } catch (e) {
+            return false;
+        }
+    }
+
+    /**
+     * Switch to the welcome project if we're not already there. Returns a
+     * native Promise that resolves once the switch completes (or
+     * immediately if no switch is needed). openProject returns a jQuery
+     * deferred, so we adapt via jsPromise and swallow rejections so
+     * downstream onboarding still runs against whatever project ended up
+     * open.
+     */
+    function _switchToWelcomeProject() {
+        const welcomePath = ProjectManager.getWelcomeProjectPath();
+        const currentPath = ProjectManager.getProjectRoot().fullPath;
+        if (currentPath === welcomePath) {
+            return Promise.resolve();
+        }
+        console.log("Guided tour: switching to welcome project for onboarding");
+        return jsPromise(ProjectManager.openProject(welcomePath)).catch(function () { });
+    }
+
+    /**
+     * If the app was bumped to a newer version since we last recorded a
+     * boot, switch to the welcome project and surface the "newly added
+     * features" markdown there (the tour's intended onboarding context).
+     * - First time we see this user: just record current and return; the
+     *   one-shot PhoenixTour handles fresh-user onboarding.
+     * - Same version as recorded: no-op.
+     * - Newer version than recorded: switch project + run newFeature.init.
+     * - Lower version (downgrade): no-op, leave state untouched so a
+     *   future re-upgrade to the recorded version doesn't re-fire.
+     */
+    function _maybeShowNewFeaturesForVersionChange() {
+        const current = _currentAppVersion();
+        if (!current) {
+            return;
+        }
+        const lastSeen = userAlreadyDidAction.lastSeenAppVersion;
+        if (lastSeen === current) {
+            return;
+        }
+        if (!lastSeen) {
+            // First time we're recording — no prior to compare against.
+            userAlreadyDidAction.lastSeenAppVersion = current;
+            PhStore.setItem(GUIDED_TOUR_LOCAL_STORAGE_KEY, JSON.stringify(userAlreadyDidAction));
+            return;
+        }
+        if (!_isNewerVersion(current, lastSeen)) {
+            // Downgrade — don't refresh, don't update state, so a
+            // future re-upgrade to lastSeen doesn't fire again.
+            return;
+        }
+        _switchToWelcomeProject().then(function () {
+            newFeature.init();
+            userAlreadyDidAction.lastSeenAppVersion = current;
+            PhStore.setItem(GUIDED_TOUR_LOCAL_STORAGE_KEY, JSON.stringify(userAlreadyDidAction));
+        });
+    }
+
     const surveyLinksURL = "https://updates.phcode.io/surveys.json";
 
     // All popup notifications will show immediately on boot, we don't want to interrupt user amidst his work
@@ -280,6 +351,11 @@ define(function (require, exports, module) {
         tourStarted = true;
         _showBeautifyNotification();
         _showSurveys();
+        // PhoenixTour is a once-per-lifetime overlay tour with its own
+        // internal _shouldRun gate; safe to call every boot.
         PhoenixTour.startTour();
+        // On a higher-version change, land on the welcome project and
+        // surface the newly-added-features markdown.
+        _maybeShowNewFeaturesForVersionChange();
     };
 });

src/extensionsIntegrated/Phoenix/main.js

@@ -26,7 +26,6 @@ define(function (require, exports, module) {
     const serverSync   = require("./serverSync"),
         newProject   = require("./new-project"),
         defaultProjects   = require("./default-projects"),
-        newFeature   = require("./newly-added-features"),
         AppInit      = require("utils/AppInit"),
         Strings      = require("strings"),
         Dialogs      = require("widgets/Dialogs"),
@@ -95,7 +94,6 @@ define(function (require, exports, module) {
         serverSync.init();
         defaultProjects.init();
         newProject.init();
-        newFeature.init();
         _detectUnSupportedBrowser();
         _persistBrowserStorage();
     });

src/extensionsIntegrated/Phoenix/new-project.js

@@ -101,7 +101,6 @@ define(function (require, exports, module) {
         Metrics.countEvent(Metrics.EVENT_TYPE.NEW_PROJECT, "dialogue", "close");
         newProjectDialogueObj.close();
         exports.trigger(exports.EVENT_NEW_PROJECT_DIALOGUE_CLOSED);
-        guidedTour.startTourIfNeeded();
     }
 
     function showErrorDialogue(title, message) {
@@ -149,6 +148,18 @@ define(function (require, exports, module) {
     let _bootDoneDeferred = new $.Deferred();
     let _bootDonePromise = jsPromise(_bootDoneDeferred.promise());
 
+    // Fire the guided tour once on every boot, regardless of how the
+    // new-project dialog flow resolved. Previously this was called from
+    // a few specific paths (closeDialogue, init when welcome screen
+    // disabled), which left users in non-default projects on native app
+    // never seeing the tour. The individual notifications inside
+    // startTourIfNeeded (beautify hint, surveys, one-shot PhoenixTour
+    // overlay, newly-added-features markdown on version bump) all have
+    // their own internal gating so it's safe to call every boot.
+    _bootDonePromise.then(function () {
+        guidedTour.startTourIfNeeded();
+    });
+
     function onBootComplete() {
         return _bootDonePromise;
     }
@@ -158,7 +169,6 @@ define(function (require, exports, module) {
         const shouldShowWelcome = PhStore.getItem("new-project.showWelcomeScreen") || 'Y';
         if(shouldShowWelcome !== 'Y') {
             Metrics.countEvent(Metrics.EVENT_TYPE.NEW_PROJECT, "dialogue", "disabled");
-            guidedTour.startTourIfNeeded();
             _bootDoneDeferred.resolve();
             return;
         }