scenescout 3.13.0 → 3.14.0

package/dist/engine/authloss.js

@@ -14,6 +14,18 @@
 export const LOGIN_ROUTE_RE = /\/(login|signin|sign-in|auth)(\/|$)/;
 /** Consecutive login bounces before we stop assuming it is a permission wall. */
 export const AUTH_LOSS_STREAK = 3;
+/**
+ * Should this loss be answered by re-attaching from the role's saved profile?
+ *
+ * Only a session attached by role has a profile that `scenescout login` (or
+ * another process) may have refreshed since, so only it has something to
+ * re-read. A storage-state file or an anonymous session is reported as
+ * before. Once per session: a second loss means the refresh did not hold,
+ * and retrying on a loop would hide a dead profile behind endless recoveries.
+ */
+export function shouldReattach(opts) {
+    return opts.streak >= AUTH_LOSS_STREAK && opts.signIn === "role" && !opts.alreadyReattached;
+}
 export class AuthLossTracker {
     /** Consecutive navigations that ended on a login page. */
     streak = 0;
@@ -21,6 +33,37 @@ export class AuthLossTracker {
     reported = false;
     /** Notice for the in-flight call, consumed exactly once by take(). */
     pending = "";
+    /** How the session signed in; set by beginSession. */
+    signIn = "none";
+    /** The role label of the session, for the notices. */
+    role = "";
+    /** What each navigation of the current streak asked for, in order. */
+    streakTargets = [];
+    /** A re-attach this navigation earned and the engine has not taken yet. */
+    due = null;
+    /** Taken by the engine: the next recorded navigation says whether it worked. */
+    awaiting = null;
+    /** What happened to this session's one re-attach. */
+    outcome = null;
+    /** Notices a batch (crawl) must still say at its end, since it discards the per-route ones. */
+    batchNotes = [];
+    /**
+     * Start tracking a newly attached session. An explicit attach is new
+     * credentials: the streak, the verdict and the one re-attach start afresh,
+     * so a new session neither inherits a dead one's bounces nor names its routes.
+     */
+    beginSession(signIn, role) {
+        this.signIn = signIn;
+        this.role = role;
+        this.streak = 0;
+        this.streakTargets = [];
+        this.reported = false;
+        this.pending = "";
+        this.due = null;
+        this.awaiting = null;
+        this.outcome = null;
+        this.batchNotes = [];
+    }
     /**
      * Did a navigation to `requested` end up on a login screen?
      *
@@ -46,14 +89,14 @@ export class AuthLossTracker {
      *
      * `bounced` decides both the streak and whether the route counts as covered;
      * the caller owns the memory writes, because ownership of the store belongs
-     * to the engine, not to this tracker.
+     * to the engine, not to this tracker. `target` is what the caller navigated
+     * to (a path with its real ids, where `requestedRoute` is the normalized
+     * route), which a re-attach goes back to; it defaults to the route.
      */
     record(opts) {
         const { requestedRoute, landedRoute, bounced, role } = opts;
-        if (bounced)
-            this.streak += 1;
-        else
-            this.streak = 0;
+        const target = opts.target ?? requestedRoute;
+        this.due = null;
         const divergence = landedRoute === requestedRoute
             ? ""
             : `⚠ REDIRECTED: asked for ${requestedRoute}, landed on ${landedRoute}` +
@@ -61,8 +104,101 @@ export class AuthLossTracker {
                     ? ` — this is a login page, so the route is NOT counted as covered.`
                     : ` — the app redirected; the route counts as covered for role '${role}'.`) +
                 `\n`;
+        if (this.awaiting) {
+            this.settleReattach(requestedRoute, target, bounced, divergence);
+            return;
+        }
+        if (bounced) {
+            this.streak += 1;
+            this.streakTargets.push(target);
+        }
+        else {
+            this.streak = 0;
+            this.streakTargets = [];
+        }
+        if (shouldReattach({ streak: this.streak, signIn: this.signIn, alreadyReattached: this.outcome !== null })) {
+            // The verdict is replaced by the recovery's own notice once the engine
+            // has re-attached; if it never does (the call threw), the verdict stands.
+            this.due = { returnTo: target, retry: [...new Set(this.streakTargets)].filter((t) => t !== target) };
+        }
         this.pending = this.banner() + divergence;
     }
+    /**
+     * The re-attach this navigation earned, if any: consumed once, and from then
+     * on this session has used its one re-attach. `revisits` says which of the
+     * streak's other targets the caller will visit again itself (a crawl, its own
+     * paths); the plan it gets back holds only those, and the notice asks for the rest.
+     */
+    takeReattach(opts = {}) {
+        const plan = this.due;
+        this.due = null;
+        if (!plan)
+            return null;
+        const revisits = opts.revisits;
+        this.awaiting = revisits
+            ? { returnTo: plan.returnTo, retry: plan.retry.filter(revisits), left: plan.retry.filter((t) => !revisits(t)) }
+            : { returnTo: plan.returnTo, retry: [], left: plan.retry };
+        this.outcome = { kind: "failed", why: "it had not finished" };
+        return { returnTo: this.awaiting.returnTo, retry: this.awaiting.retry };
+    }
+    /** Whether a re-attach was taken and the navigation that decides it has not been recorded. */
+    get reattaching() {
+        return this.awaiting !== null;
+    }
+    /** The profile could not be applied, or the page to go back to never loaded: the loss is reported, with why. */
+    abortReattach(why) {
+        this.awaiting = null;
+        this.outcome = { kind: "failed", why };
+        const note = `The session tried to re-attach once from role '${this.role}''s saved profile, but ${why}.`;
+        this.pending = this.banner(this.lossTail(note));
+        this.batchNotes.push(`⚠ ${note}\n`);
+    }
+    /** The navigation after a re-attach decides it: signed in again, or not. */
+    settleReattach(requestedRoute, target, bounced, divergence) {
+        const plan = this.awaiting;
+        this.awaiting = null;
+        if (bounced) {
+            // Still on a login page with the latest profile: that profile is dead too.
+            this.streak = Math.max(this.streak, AUTH_LOSS_STREAK);
+            this.streakTargets.push(target);
+            const why = `its latest saved profile landed on a login page as well, so that profile has expired too`;
+            this.outcome = { kind: "failed", why };
+            const note = `The session re-attached once from role '${this.role}''s saved profile, but ${why}.`;
+            this.pending = this.banner(this.lossTail(note)) + divergence;
+            this.batchNotes.push(`⚠ ${note}\n`);
+            return;
+        }
+        this.streak = 0;
+        this.streakTargets = [];
+        // The loss was answered: a later batch verdict must not claim this session is dead.
+        this.reported = false;
+        this.outcome = { kind: "recovered", route: requestedRoute };
+        const others = (plan.retry.length === 0 ? "" : ` The other routes that bounced (${plan.retry.join(", ")}) are visited again in this sweep.`) +
+            (plan.left.length === 0 ? "" : ` The other routes that bounced before it (${plan.left.join(", ")}) are still NOT covered: visit them again.`);
+        const note = `↻ SESSION RE-ATTACHED — its sign-in was lost, so it re-attached once from role '${this.role}''s latest saved profile and ` +
+            `is signed in again at ${requestedRoute}.${others} This happens once per session: a second loss is reported, not retried.\n`;
+        this.pending = note + divergence;
+        this.batchNotes.push(note);
+    }
+    /** The end of a loss once the one re-attach is spent: what happened, and that it is not retried. */
+    lossTail(note) {
+        return ` ${note} It is not retried: record the profile again with \`scenescout login\` for role '${this.role}' and re-attach.`;
+    }
+    /**
+     * One line on what this session's re-attach did, for whoever hands its
+     * results on (a lane's report). Empty when it never re-attached.
+     */
+    reattachSummary() {
+        if (!this.outcome)
+            return "";
+        if (this.outcome.kind === "recovered")
+            return `its sign-in was lost and it re-attached once from role '${this.role}''s saved profile, continuing from ${this.outcome.route}`;
+        return `its sign-in was lost and re-attaching from role '${this.role}''s saved profile did not recover it: ${this.outcome.why}`;
+    }
+    /** Start a batch (crawl): its end-of-batch notes cover only what happened during it. */
+    beginBatch() {
+        this.batchNotes = [];
+    }
     /**
      * The verdict, once the streak says the session is dead.
      *
@@ -74,15 +210,18 @@ export class AuthLossTracker {
      * collapses repeats to "nothing new" — the signal decayed exactly as the
      * problem got worse.
      */
-    banner() {
+    banner(tail) {
         if (this.streak < AUTH_LOSS_STREAK)
             return "";
         const first = !this.reported;
         this.reported = true;
+        // After the session's one re-attach, a later loss says so rather than implying a retry is still to come.
+        const spent = tail ?? (this.outcome !== null ? this.lossTail(`This session already re-attached once from role '${this.role}''s saved profile.`) : "");
         return (`⚠ SESSION AUTH LOST — ${this.streak} consecutive navigations were redirected to a login page. ` +
             `The credentials this session attached with have almost certainly expired. ` +
             `Nothing tested past this point is meaningful: re-attach with a fresh storage state before continuing.` +
             (first ? ` Routes bounced this way are recorded as NOT covered, so the completion contract still sees them as gaps.` : "") +
+            spent +
             `\n`);
     }
     /**
@@ -115,9 +254,11 @@ export class AuthLossTracker {
      * whatever the final route did.
      */
     batchVerdict() {
+        const notes = this.batchNotes.join("");
         if (!this.reported)
-            return "";
-        return (`⚠ SESSION AUTH LOST during this sweep — navigations were redirected to a login page. ` +
+            return notes;
+        return (notes +
+            `⚠ SESSION AUTH LOST during this sweep — navigations were redirected to a login page. ` +
             `The credentials this session attached with have almost certainly expired, so routes crawled after that ` +
             `point tested a logged-out app. They are recorded as NOT covered; re-attach with a fresh storage state ` +
             `and crawl again.\n`);

package/dist/engine/brief.js

@@ -85,6 +85,12 @@ export function laneName(modules, index) {
     const name = modules.length > 1 ? `${base}+${modules.length - 1}` : base || `lane-${index + 1}`;
     return name.slice(0, LANE_NAME_MAX);
 }
+/** How a lane signs in, as scout_attach arguments: by saved role, by a storage-state file, or not at all. */
+function signInArgument(opts) {
+    if (!opts.role || opts.role === "anonymous")
+        return "";
+    return opts.roleProfile ? `, role: "${opts.role}"` : `, storageStatePath: "<${opts.role}>"`;
+}
 /** The lanes to run, each with the objective to attach with. */
 export function planLanes(routes, laneCount, opts = {}) {
     return splitRoutes(routes, laneCount).map((lane, i) => ({
@@ -124,7 +130,7 @@ export function formatBriefs(briefs, opts = {}) {
         `LANE PLAN — ${briefs.length} lane(s) over ${briefs.reduce((n, b) => n + b.routes.length, 0)} route(s).`,
         ``,
         `Give each lane its own agent. Every lane attaches with its own session name, so the browsers run genuinely in parallel, and lands on its own first route rather than the home page:`,
-        `  scout_attach { session: "<lane>", url: "<origin><landing>", projectPath, mode: "${mode}"${opts.role ? `, storageStatePath: "<${opts.role}>"` : ""}, objective: "<objective>" }`,
+        `  scout_attach { session: "<lane>", url: "<origin><landing>", projectPath, mode: "${mode}"${signInArgument(opts)}, objective: "<objective>" }`,
         ``,
         `Rules to pass on, which a hand-written brief tends to drop:`,
         `  · A lane works ITS routes only. Two lanes auditing the same register while a third module is never opened is the failure this plan exists to prevent — and route coverage will look complete either way. A defect on a page it does not own is that page's lane's to file.`,