copilot-operator 0.1.9 → 0.1.11

package/dist/src/protocol/parser.js

@@ -60,8 +60,83 @@ export function stripCitations(text) {
         return undefined;
     return text.replace(/\s*【[^】]*】/g, '').replace(/[ 	]+$/gm, '').trim();
 }
+/*
+ * Prose that arrived in another shape.
+ *
+ * `tried`, `needed`, `notes` and `summary` are sentences for a person to read; nothing in them is
+ * run. A chat that writes `tried` as a list of objects — `{"approach": "…", "result": "…"}` — has
+ * said exactly what was asked, in a shape the schema did not expect, and refusing the whole reply
+ * for it cost a format round each time and, three in a row, the task: it ended "failed" with the
+ * work done and its results already recorded. So these fields are read as text whatever shape they
+ * come in, and the reading is reported. The fields that are acted on — `status`, `steps` and
+ * everything in them — are never coerced: a step the runner would have to guess at is not run.
+ */
+const PROSE_KEYS = ['approach', 'what', 'tried', 'attempt', 'action', 'description', 'text', 'summary', 'detail', 'result', 'outcome', 'why', 'reason', 'needed'];
+function proseOf(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(proseOf).filter((x) => x.trim()).join('\n');
+    if (typeof value === 'object') {
+        const record = value;
+        const named = PROSE_KEYS.filter((k) => typeof record[k] === 'string' && record[k].trim()).map((k) => record[k]);
+        if (named.length > 0)
+            return named.join(' — ');
+        const strings = Object.values(record).filter((v) => typeof v === 'string' && v.trim() !== '');
+        return strings.length > 0 ? strings.join(' — ') : JSON.stringify(value);
+    }
+    return String(value);
+}
+export function normaliseProse(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return { value, coerced: [] };
+    const out = { ...value };
+    const coerced = [];
+    for (const key of ['notes', 'summary', 'needed']) {
+        if (key in out && out[key] !== undefined && typeof out[key] !== 'string') {
+            out[key] = proseOf(out[key]);
+            coerced.push(key);
+        }
+    }
+    if ('tried' in out && out.tried !== undefined) {
+        const tried = out.tried;
+        if (typeof tried === 'string') {
+            out.tried = tried.trim() ? [tried] : [];
+            coerced.push('tried');
+        }
+        else if (Array.isArray(tried) && tried.some((t) => typeof t !== 'string')) {
+            out.tried = tried.map(proseOf).filter((t) => t.trim() !== '');
+            tried.forEach((t, i) => {
+                if (typeof t !== 'string')
+                    coerced.push(`tried.${i}`);
+            });
+        }
+    }
+    return { value: out, coerced };
+}
+/** What each field must look like, said in the message that asks for a reformatted reply. */
+const FIELD_SHAPES = [
+    [/^status$/, '"status" is one of "continue", "done", "blocked"'],
+    [/^steps(\.|$)/, '"steps" is a list of {"id": 1, "type": "command", "cmd": "the command"} ("shell", "expect", "timeoutSec" optional)'],
+    [/^tried(\.|$)/, '"tried" is a list of plain strings, one sentence per approach'],
+    [/^deviations(\.|$)/, '"deviations" is a list of {"instruction": "…", "did": "…", "why": "…"} with plain strings'],
+    [/^disputed(\.|$)/, '"disputed" is a list of {"finding": "…", "why": "…", "evidence": "…"} with plain strings'],
+    [/^(summary|notes|needed)$/, '"summary", "notes" and "needed" are plain strings'],
+];
+const FORMAT_EXAMPLE = [
+    '```json',
+    '{"status": "continue", "notes": "what this round does", "steps": [{"id": 1, "type": "command", "cmd": "npm test"}]}',
+    '```',
+    'or, to end: {"status": "done", "summary": "several sentences on what was done and what it shows"}',
+    'or {"status": "blocked", "summary": "…", "tried": ["first approach", "second approach"], "needed": "what would unblock it"}',
+].join('\n');
 export function parseReply(markdown, opts) {
     const candidates = findJsonCandidates(markdown);
+    const paths = new Set();
     if (candidates.length === 0) {
         return {
             ok: false,
@@ -80,9 +155,12 @@ export function parseReply(markdown, opts) {
                 errors.push(`JSON.parse failed: ${e.message}`);
                 continue;
             }
-            const result = ReplySchema.safeParse(value);
+            const prose = normaliseProse(value);
+            const result = ReplySchema.safeParse(prose.value);
             if (!result.success) {
                 errors.push(result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; '));
+                for (const i of result.error.issues)
+                    paths.add(i.path.join('.') || '(root)');
                 continue;
             }
             const reply = result.data;
@@ -106,6 +184,7 @@ export function parseReply(markdown, opts) {
                 done: reply.status === 'done' || (markerHit && hasSummary && !blocked),
                 blocked,
                 json: text.trim(),
+                ...(prose.coerced.length > 0 ? { coerced: prose.coerced } : {}),
             };
         }
     }
@@ -113,6 +192,7 @@ export function parseReply(markdown, opts) {
         ok: false,
         reason: 'invalid-json',
         detail: errors.slice(0, 4).join(' | '),
+        ...(paths.size > 0 ? { paths: [...paths] } : {}),
     };
 }
 /**
@@ -162,15 +242,28 @@ export function parseReview(markdown, opts) {
     return { ok: false, reason: 'invalid-json', detail: errors.slice(0, 4).join(' | ') };
 }
 /** The message sent back when a reply did not validate. Names the problem, nothing else. */
+/**
+ * The message that asks for the same answer again, in the format.
+ *
+ * It names each rejected field with the shape it must have, gives a valid example, and says what
+ * did not happen: nothing from the rejected reply was run, so the results of the steps before it
+ * stand and the answer only needs reformatting. Without that last part a chat told "invalid" tends
+ * to start the round again, or to keep the same shape and change the wording, and the rounds run out.
+ */
 export function formatErrorMessage(fail, attempt, maxAttempts) {
+    const shapes = [...new Set((fail.paths ?? []).flatMap((p) => FIELD_SHAPES.filter(([re]) => re.test(p)).map(([, s]) => s)))];
     return [
-        `Your last reply did not match the required format (attempt ${attempt} of ${maxAttempts}).`,
+        `Your last reply did not match the required format (format retry ${attempt} of ${maxAttempts}).`,
         fail.reason === 'no-json-block'
             ? 'There was no fenced json code block in it.'
             : `The json block did not validate: ${fail.detail}`,
-        'Resend the same answer as exactly one fenced code block tagged json, with the fields',
-        'status, steps and notes, and nothing else tagged json in the reply.',
-    ].join(' ');
+        shapes.length > 0 ? `What those fields must be: ${shapes.join('; ')}.` : '',
+        'Only the format is wrong. Nothing from that reply was run, and the results of the steps before it stand.',
+        'Send the same answer again, reformatted, as exactly one fenced code block tagged json — do not start over and do not change what it asks for. For example:',
+        FORMAT_EXAMPLE,
+    ]
+        .filter(Boolean)
+        .join('\n');
 }
 /**
  * Spots a command that arrived damaged rather than badly written.

package/dist/src/session/compose.js

@@ -11,7 +11,7 @@ const TASK_HEADER = '## Task';
  * and a note that is empty simply leaves nothing behind.
  */
 function runnerBlock(input) {
-    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
+    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.approachesNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
     return notes.length > 0 ? `${notes.join('\n\n')}\n\n` : '';
 }
 /**

package/dist/src/session/exports.js

@@ -399,6 +399,7 @@ async function domainTask(session, task, runsDir) {
             scope: task.scope ?? [],
             scopeReverted: task.scopeReverted ?? [],
             handoff: task.handoff ?? null,
+            stopCode: task.stopCode ?? null,
             prompt: p.prompt,
             expected: p.expected,
             level2: task.level2,

package/dist/src/session/handoff.js

@@ -29,7 +29,7 @@ export function composeHandoff(task, notRun = []) {
     if ((vcs.suspicious?.length ?? 0) > 0 || (vcs.foreignCommits?.length ?? 0) > 0)
         manual.push('look at the committed files and commits listed above');
     return {
-        outcome: { status: task.status, ...(task.reason ? { reason: task.reason } : {}) },
+        outcome: { status: task.status, ...(task.reason ? { reason: task.reason } : {}), ...(task.stopCode ? { stopCode: task.stopCode } : {}) },
         changedFiles: (vcs.files ?? []).map((f) => ({ path: f.path, added: f.added, removed: f.removed })),
         validation: (task.checkResults ?? []).map((c) => ({ name: c.name, passed: c.passed })),
         ...(task.review ? { review: { verdict: task.review.verdict, open: openFindings.length } } : {}),

package/dist/src/session/store.js

@@ -42,6 +42,47 @@ export const DEFAULT_MIRROR = {
     respectGitignore: true,
     includeEnvFiles: false,
 };
+/**
+ * Applies an edit to a task: the one place the rule about a new intent lives.
+ *
+ * A task given a new prompt is a new question. The checks the reviews of its earlier attempts
+ * added were findings about the old question, and inheriting them gated the new one on work it
+ * no longer asks for: a maintenance task rewritten as an audit still had to pass "the build uses
+ * the new config", and went blocked on an artificial finding. So a changed prompt drops them, with
+ * the reason kept beside each, and they stay on the record. The plan's own checks are not guessed
+ * at: whoever writes the new prompt says which still apply (the edit form and the new-prompt
+ * dialog both show them), and `checks` in the patch is that answer. A re-run with the same prompt
+ * keeps everything, because it is the same question asked again.
+ */
+export function applyTaskPatch(t, patch) {
+    const newPrompt = patch.prompt !== undefined && patch.prompt.trim() !== '' && patch.prompt.trim() !== t.prompt.trim();
+    if (patch.title !== undefined)
+        t.title = patch.title.trim() || t.title;
+    if (patch.prompt !== undefined && patch.prompt.trim())
+        t.prompt = patch.prompt;
+    if (patch.level2 !== undefined)
+        t.level2 = patch.level2;
+    if (patch.vcsPlan !== undefined)
+        t.vcsPlan = tidyVcsPlan(patch.vcsPlan);
+    if (patch.checks !== undefined)
+        t.checks = patch.checks.filter((c) => c.name.trim() !== '');
+    if (patch.readOnly !== undefined) {
+        if (patch.readOnly)
+            t.readOnly = true;
+        else
+            delete t.readOnly;
+    }
+    if (patch.scope !== undefined) {
+        const scope = patch.scope.map((p) => p.trim()).filter(Boolean);
+        if (scope.length > 0)
+            t.scope = scope;
+        else
+            delete t.scope;
+    }
+    if (newPrompt && t.reviewChecks?.length) {
+        t.reviewChecks = t.reviewChecks.map((rc) => rc.state === 'dropped' ? rc : { ...rc, state: 'dropped', droppedBecause: 'the task was given a new prompt; this was a finding about the old one' });
+    }
+}
 export class SessionStore {
     defaultLevel1Path;
     dir;
@@ -358,22 +399,14 @@ export class SessionStore {
                     continuing: t.continuing,
                     buildsOn: t.buildsOn,
                     freshRetry: t.freshRetry,
+                    stopCode: t.stopCode,
                     scope: t.scope,
                     scopeReverted: t.scopeReverted,
                     vcs: t.vcs,
                 },
             ];
             // An edit is applied only after the old attempt has been put beyond its reach.
-            if (patch.title !== undefined)
-                t.title = patch.title.trim() || t.title;
-            if (patch.prompt !== undefined && patch.prompt.trim())
-                t.prompt = patch.prompt;
-            if (patch.level2 !== undefined)
-                t.level2 = patch.level2;
-            if (patch.vcsPlan !== undefined)
-                t.vcsPlan = tidyVcsPlan(patch.vcsPlan);
-            if (patch.checks !== undefined)
-                t.checks = patch.checks.filter((c) => c.name.trim() !== '');
+            applyTaskPatch(t, patch);
             t.attempt = (t.attempt ?? 1) + 1;
             t.status = 'queued';
             t.iterations = 0;
@@ -404,6 +437,7 @@ export class SessionStore {
             t.handoff = undefined;
             t.scopeReverted = undefined;
             t.freshRetry = undefined;
+            t.stopCode = undefined;
             // The branch of the finished attempt stays in the repository and stays on the record
             // above; the next attempt gets its own, cut from the same commit this one started at.
             t.vcs = undefined;

package/dist/src/transport/copilotTransport.js

@@ -57,65 +57,65 @@ export class SendRejectedError extends Error {
  * impossible — the runner notes it before the click and waits for it to move, so a copy that
  * did not happen reads as a failure rather than as the previous answer.
  */
-export const CLIPBOARD_GUARD = `(() => {
-  const state = { text: '', seq: 0 };
-  try {
-    Object.defineProperty(window, '__copClipboard', { value: state, enumerable: false });
-  } catch (e) {
-    window.__copClipboard = state;
-  }
-
-  const remember = (text) => {
-    if (typeof text !== 'string' || text.length === 0) return;
-    state.text = text;
-    state.seq += 1;
-  };
-
-  const clip = navigator.clipboard;
-  if (clip) {
-    try {
-      Object.defineProperty(clip, 'writeText', {
-        configurable: true,
-        writable: true,
-        value: (text) => {
-          remember(String(text));
-          return Promise.resolve();
-        },
-      });
-    } catch (e) { /* a frame that will not let its clipboard be replaced reads as a failure later */ }
-
-    try {
-      Object.defineProperty(clip, 'write', {
-        configurable: true,
-        writable: true,
-        value: async (items) => {
-          for (const item of items || []) {
-            try {
-              if (item && item.types && item.types.indexOf('text/plain') >= 0) {
-                remember(await (await item.getType('text/plain')).text());
-              }
-            } catch (e) { /* one unreadable item is not a reason to drop the rest */ }
-          }
-        },
-      });
-    } catch (e) { /* as above */ }
-  }
-
-  // The old way: select text in a hidden field, then execCommand('copy'). The selection is
-  // exactly the text being copied, so it is taken and the command is never run.
-  try {
-    const realExec = document.execCommand.bind(document);
-    document.execCommand = (command, ...rest) => {
-      if (String(command).toLowerCase() === 'copy') {
-        const selected = String(window.getSelection() || '');
-        if (selected.length > 0) {
-          remember(selected);
-          return true;
-        }
-      }
-      return realExec(command, ...rest);
-    };
-  } catch (e) { /* as above */ }
+export const CLIPBOARD_GUARD = `(() => {
+  const state = { text: '', seq: 0 };
+  try {
+    Object.defineProperty(window, '__copClipboard', { value: state, enumerable: false });
+  } catch (e) {
+    window.__copClipboard = state;
+  }
+
+  const remember = (text) => {
+    if (typeof text !== 'string' || text.length === 0) return;
+    state.text = text;
+    state.seq += 1;
+  };
+
+  const clip = navigator.clipboard;
+  if (clip) {
+    try {
+      Object.defineProperty(clip, 'writeText', {
+        configurable: true,
+        writable: true,
+        value: (text) => {
+          remember(String(text));
+          return Promise.resolve();
+        },
+      });
+    } catch (e) { /* a frame that will not let its clipboard be replaced reads as a failure later */ }
+
+    try {
+      Object.defineProperty(clip, 'write', {
+        configurable: true,
+        writable: true,
+        value: async (items) => {
+          for (const item of items || []) {
+            try {
+              if (item && item.types && item.types.indexOf('text/plain') >= 0) {
+                remember(await (await item.getType('text/plain')).text());
+              }
+            } catch (e) { /* one unreadable item is not a reason to drop the rest */ }
+          }
+        },
+      });
+    } catch (e) { /* as above */ }
+  }
+
+  // The old way: select text in a hidden field, then execCommand('copy'). The selection is
+  // exactly the text being copied, so it is taken and the command is never run.
+  try {
+    const realExec = document.execCommand.bind(document);
+    document.execCommand = (command, ...rest) => {
+      if (String(command).toLowerCase() === 'copy') {
+        const selected = String(window.getSelection() || '');
+        if (selected.length > 0) {
+          remember(selected);
+          return true;
+        }
+      }
+      return realExec(command, ...rest);
+    };
+  } catch (e) { /* as above */ }
 })();`;
 export class CopilotTransport {
     opts;
@@ -271,7 +271,7 @@ export class CopilotTransport {
             'sign-in': 'The profile is signed out. Run "cop login".',
             unknown: 'The page is not the Microsoft 365 Copilot chat.',
         };
-        throw new Error(`${explain[where] ?? explain.unknown}
+        throw new Error(`${explain[where] ?? explain.unknown}
 Current URL: ${url}`);
     }
     /**
@@ -680,14 +680,77 @@ Current URL: ${url}`);
         }
         await row.click({ timeout: 8_000 }).catch(() => undefined);
     }
-    /** Closes the picker, submenu included. */
+    /**
+     * Whether the model picker is open: its button says so (`aria-expanded`), or its rows are on screen.
+     * Both, because either alone has been wrong: rows can be mid-animation after the menu closed, and a
+     * button re-rendered by the page can lose the attribute while the menu is still up.
+     */
+    async modelMenuOpen() {
+        const button = await this.resolveModelButton(1_000);
+        const expanded = button ? await button.getAttribute('aria-expanded').catch(() => null) : null;
+        if (expanded === 'true')
+            return true;
+        return (await this.readMenuRows()).length > 0;
+    }
+    /**
+     * Closes the picker, submenu included, and makes sure it is closed.
+     *
+     * Escape pressed on the page was all this did, three times, and then it gave up without a word.
+     * Live, that left the model list open over the chat after a check of the model: Escape goes to
+     * whatever has focus, and after a click dispatched on a row, or no click at all because the model
+     * was already chosen, focus was not in the menu, so nothing heard it. Each way a person would close
+     * it is tried in turn, and the menu is looked at after each: Escape; Escape sent to the menu itself;
+     * the picker button again (it toggles); a click outside the menu, in the composer, which a Fluent
+     * popup takes as "close". A menu still open after all of them is reported, not passed over.
+     */
     async closeMenu() {
-        for (let i = 0; i < 3; i += 1) {
-            await this.p.keyboard.press('Escape').catch(() => undefined);
-            await this.p.waitForTimeout(200);
-            if ((await this.readMenuRows()).length === 0)
+        const ways = [
+            ['escape', async () => await this.p.keyboard.press('Escape')],
+            [
+                'escape in the menu',
+                async () => {
+                    for (const selector of Model.popupSelectors.slice(0, 2)) {
+                        const menu = this.p.locator(`${selector}:visible`).last();
+                        if ((await menu.count()) > 0) {
+                            await menu.press('Escape', { timeout: 2_000 });
+                            return;
+                        }
+                    }
+                },
+            ],
+            [
+                'the picker button',
+                async () => {
+                    const button = await this.resolveModelButton(1_000);
+                    // Only while the button itself says the menu is open: clicking it otherwise would open it.
+                    if (button && (await button.getAttribute('aria-expanded').catch(() => null)) === 'true')
+                        await button.click({ timeout: 3_000 });
+                },
+            ],
+            [
+                'a click outside',
+                async () => {
+                    const composer = this.composer();
+                    if ((await composer.count().catch(() => 0)) > 0 && (await composer.isVisible().catch(() => false)))
+                        await composer.click({ timeout: 3_000 });
+                    else
+                        await this.p.mouse.click(4, 4);
+                },
+            ],
+        ];
+        for (const [how, act] of ways) {
+            if (!(await this.modelMenuOpen()))
+                return;
+            await act().catch(() => undefined);
+            await this.p.waitForTimeout(250);
+            if (!(await this.modelMenuOpen())) {
+                if (how !== 'escape')
+                    this.emit('model-menu-closed', { how });
                 return;
+            }
         }
+        if (await this.modelMenuOpen())
+            this.emit('model-menu-stuck', { tried: ways.map(([how]) => how) });
     }
     /** The first popup container that becomes visible after the picker is clicked. */
     async waitForPopup(timeoutMs = 8_000) {
@@ -750,12 +813,29 @@ Current URL: ${url}`);
             await this.closeMenu();
             return { ok: false, current: before, reason: `The picker does not offer "${name}" any more.` };
         }
+        /*
+         * Already the one in force: close the menu and say so, without clicking.
+         *
+         * The button cannot answer this on its own, because it shortens names — "GPT 5.6 Think deeper"
+         * reads "GPT 5.6 Think" — so the exact comparison above lets a chat that is already on the
+         * model through to here. The row's own mark (`aria-checked` and its kin) is the answer. The
+         * click it used to get did nothing in Copilot: the row already in force ignores it, the menu
+         * stayed open over the composer, and the run went on with the model list hanging on screen.
+         */
+        if (target.selected) {
+            await this.closeMenu();
+            this.emit('model-already-selected', { model: target.name, buttonShows: before });
+            return { ok: true, current: target.name };
+        }
         if (target.disabled) {
             await this.closeMenu();
             return { ok: false, current: before, reason: `"${name}" is shown but not available right now.` };
         }
         await this.clickMenuRow(target.name, inSubmenu);
         await this.p.waitForTimeout(1_000);
+        // Whatever the click did, the menu is not left open over the chat: a build that keeps it open
+        // after a choice, or a click that did not land, would otherwise leave it for the next message.
+        await this.closeMenu();
         const after = await this.currentModel();
         // The button shows the choice, so it is the check. It also **shortens** it: picking
         // "GPT 5.6 Quick response" leaves the button reading "GPT 5.6 Quick". So a shown value

package/dist/src/vcs/scope.js

@@ -65,12 +65,13 @@ export function inScope(path, scope) {
  * Puts back every change outside `scope`. Only for a repository whose tree was clean when the task
  * started, which is why the caller passes the repository only when version control is active.
  */
-export async function enforceScope(dir, scope) {
+export async function enforceScope(dir, scope, nothing = false) {
     const out = { outside: [], reverted: [], failed: [] };
-    if (scope.length === 0)
+    // An empty scope allows everything; `nothing` is the read-only task, which allows no change at all.
+    if (scope.length === 0 && !nothing)
         return out;
     const changed = await workingTreePaths(dir);
-    out.outside = changed.filter((p) => !inScope(p, scope));
+    out.outside = nothing ? changed : changed.filter((p) => !inScope(p, scope));
     const root = resolve(dir);
     for (const rel of out.outside) {
         const abs = resolve(join(dir, rel));
@@ -107,13 +108,15 @@ export async function enforceScope(dir, scope) {
     return out;
 }
 /** What the chat is told, in the message that carries the step results. */
-export function scopeMessage(check, scope) {
+export function scopeMessage(check, scope, readOnly = false) {
     const list = (paths) => paths.slice(0, 15).join(', ') + (paths.length > 15 ? `, and ${paths.length - 15} more` : '');
     const parts = [
-        `Outside this task's scope, so put back by the runner: ${list(check.reverted)}.`,
+        `${readOnly ? 'Changed by a read-only task' : "Outside this task's scope"}, so put back by the runner: ${list(check.reverted)}.`,
         check.failed.length > 0 ? `Could not be put back: ${check.failed.map((f) => `${f.path} (${f.why})`).join('; ')}.` : '',
-        `This task may change only: ${scope.join(', ')}. If the work truly needs a file outside that, do not work around it: ` +
-            'end with status "blocked", name the file in "needed" and say why.',
+        readOnly
+            ? 'This task is read-only: it may change no file at all. Read, run and report; put what you found in your summary.'
+            : `This task may change only: ${scope.join(', ')}. If the work truly needs a file outside that, do not work around it: ` +
+                'end with status "blocked", name the file in "needed" and say why.',
     ];
     return parts.filter(Boolean).join(' ');
 }

package/dist/src/vcs/syncCommand.js

@@ -0,0 +1,105 @@
+/**
+ * The command that brings a project's current branch back to the remote's main branch, handed to
+ * the operator rather than run.
+ *
+ * Asked for after a day of runs: a project left on a task branch, with files a step created and
+ * nobody committed, wants to go back to where the team's code is. That is `fetch`, `reset --hard`
+ * to the remote's main, and `clean -fd` for the new files git does not ignore — three commands that
+ * destroy work if pointed at the wrong folder or run a minute too early. So the bot never runs them.
+ * It reads the repository, says exactly what would be lost — commits on this branch that the
+ * remote's main does not have, changed tracked files, new files — and gives the command, ready to
+ * paste into PowerShell, with a read-only preview beside it. Ignored files (`node_modules`, `.env`,
+ * build output) are left alone: `clean` without `-x` does not touch them.
+ *
+ * Nothing here writes to the repository or the network. `git fetch` is in the command, not here:
+ * what "would be lost" is computed against the remote branch as last fetched, and the page says so.
+ */
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { git, porcelainPaths } from './git.js';
+/** A string as a single-quoted PowerShell literal: nothing inside it is expanded. */
+export function psQuote(text) {
+    return `'${text.replace(/'/g, "''")}'`;
+}
+/**
+ * The two commands, for Windows PowerShell 5.1 and PowerShell 7 alike: `;` and `$LASTEXITCODE`
+ * rather than `&&`, which 5.1 does not have, so a failed fetch stops everything after it instead
+ * of resetting to a remote branch that is out of date.
+ */
+export function syncCommands(dir, remote, target) {
+    const g = `git -C ${psQuote(dir)}`;
+    return {
+        preview: [
+            `${g} fetch ${psQuote(remote)}`,
+            `${g} log --oneline ${psQuote(`${target}..HEAD`)}`,
+            `${g} status --short`,
+            `${g} clean -nd`,
+        ].join('; '),
+        command: `${g} fetch ${psQuote(remote)}; if ($LASTEXITCODE -eq 0) { ${g} reset --hard ${psQuote(target)}; ` +
+            `if ($LASTEXITCODE -eq 0) { ${g} clean -fd } }`,
+    };
+}
+const empty = (repoDir, problem) => ({
+    ok: false,
+    problem,
+    repoDir,
+    willLose: { commits: [], changed: [], untracked: [] },
+    preview: '',
+    command: '',
+});
+export async function planSync(repoDir) {
+    const inside = await git(repoDir, ['rev-parse', '--is-inside-work-tree']);
+    if (!inside.ok || inside.stdout !== 'true')
+        return empty(repoDir, `${repoDir} is not a git repository.`);
+    const branch = await git(repoDir, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    if (!branch.ok || !branch.stdout) {
+        return empty(repoDir, 'The repository is not on a branch (a detached HEAD), so there is no "current branch" to bring up to date. Check out a branch first.');
+    }
+    const remotes = (await git(repoDir, ['remote'])).stdout.split('\n').map((r) => r.trim()).filter(Boolean);
+    if (remotes.length === 0)
+        return empty(repoDir, 'The repository has no remote, so there is no remote main branch to go back to.');
+    const remote = remotes.includes('origin') ? 'origin' : remotes[0];
+    // The remote's own idea of its main branch first, then the two usual names.
+    let target = '';
+    const head = await git(repoDir, ['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`]);
+    if (head.ok && head.stdout)
+        target = head.stdout;
+    for (const name of ['main', 'master']) {
+        if (target)
+            break;
+        const found = await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${name}`]);
+        if (found.ok)
+            target = `${remote}/${name}`;
+    }
+    if (!target) {
+        return empty(repoDir, `No main branch of ${remote} is known here yet. Run ${syncCommands(repoDir, remote, `${remote}/main`).preview.split('; ')[0]} once, then look again.`);
+    }
+    const commits = await git(repoDir, ['log', '--format=%h %s', `${target}..HEAD`]);
+    const status = await git(repoDir, ['status', '--porcelain', '--untracked-files=no']);
+    const clean = await git(repoDir, ['clean', '-nd']);
+    let lastFetched;
+    try {
+        const gitDir = (await git(repoDir, ['rev-parse', '--absolute-git-dir'])).stdout;
+        lastFetched = statSync(join(gitDir, 'FETCH_HEAD')).mtime.toISOString();
+    }
+    catch {
+        /* never fetched: the page says so */
+    }
+    return {
+        ok: true,
+        repoDir,
+        branch: branch.stdout,
+        remote,
+        target,
+        ...(lastFetched ? { lastFetched } : {}),
+        willLose: {
+            commits: commits.ok && commits.stdout ? commits.stdout.split('\n') : [],
+            changed: porcelainPaths(status.stdout),
+            untracked: clean.stdout
+                .split('\n')
+                .map((l) => l.replace(/^Would remove\s+/, '').trim())
+                .filter(Boolean),
+        },
+        ...syncCommands(repoDir, remote, target),
+    };
+}