A local-first multi-agent app development platform, built on PenguinHarness
/**
* The decisions behind the page notice's "update everything on this tab" button: what the
* notice claims is waiting, and what the user is told afterwards when only some of it landed.
*
* Kept pure and apart from the pages for the reason `todo-badges.ts` is: vitest runs node-only
* here, so a rule that lives in a component is a rule nothing checks. The pages own the
* requests; everything that decides what a number MEANS is here.
*/
import type { Todo } from "./todo-badges";
/**
* The two numbers a notice may state. `added` is absent on the trails that cannot honestly
* report one — see {@link Todo.breakdown}; the notice then names the upgradable count alone
* rather than padding the sentence with a zero.
*/
export interface NoticeCounts {
added: number | null;
updated: number;
}
/**
* What the notice says is waiting, read off the SAME raised to-do that lit the nav dot. Going
* back to the underlying data for a second opinion is the one thing this must not do: a block
* claiming three updates under a dot raised for four is a bug the user cannot resolve, and it is
* exactly what two independent counts drift into.
*
* A trail with no breakdown reports its whole count as upgradable, which is what it is: a Skill
* some Agent has fallen behind on and an Agent behind the defaults generation are both things
* the Project already has an older form of.
*/
export function noticeCounts(todo: Todo): NoticeCounts {
if (todo.breakdown === undefined) return { added: null, updated: todo.count };
return { added: todo.breakdown.added, updated: todo.breakdown.updated };
}
/** How a bulk write went, in the terms the toast reports it in. */
export interface BulkOutcome {
/** Everything landed. */
allOk: boolean;
/** How many targets were written successfully. */
ok: number;
/** The labels that failed, in the order they were attempted; empty when none did. */
failed: string[];
}
/**
* Zips a settled batch back onto the labels it was launched from, so a partial failure can name
* WHICH targets are still behind.
*
* `Promise.allSettled` preserves input order, which is what makes the pairing sound — and the
* reason the labels are passed in rather than recovered from the results, which carry no
* identity of their own. Reporting only the first error (the precedent this replaces) leaves
* the user knowing that something failed and not what: on a page whose whole point is acting on
* everything at once, "3 of 5 updated" without the missing two is an unfinished sentence.
*/
export function bulkOutcome(
labels: readonly string[],
results: readonly PromiseSettledResult<unknown>[],
): BulkOutcome {
const failed: string[] = [];
let ok = 0;
results.forEach((result, i) => {
if (result.status === "fulfilled") ok += 1;
// A label the caller did not supply for this index would be a programming error, not a
// user-facing one; falling back to the index keeps the toast honest instead of blank.
else failed.push(labels[i] ?? String(i));
});
return { allOk: failed.length === 0, ok, failed };
}
/**
* How many failed targets the toast names before it stops listing.
*
* Naming them is the point of the partial-failure report, but a batch of twenty turns a
* six-second toast into a wall of text nobody finishes reading. The overflow is reported as a
* count rather than dropped silently: the reader still knows the list is not the whole of it.
*/
const MAX_NAMED_FAILURES = 8;
/** The failed labels as one string, capped. `+N` stands for the ones past the cap. */
export function failedList(failed: readonly string[], separator: string): string {
if (failed.length <= MAX_NAMED_FAILURES) return failed.join(separator);
const named = failed.slice(0, MAX_NAMED_FAILURES).join(separator);
return `${named}${separator}+${failed.length - MAX_NAMED_FAILURES}`;
}
/** The first rejection's reason, for the error text appended to a partial-failure report. */
export function firstFailure(results: readonly PromiseSettledResult<unknown>[]): unknown {
const rejected = results.find((r): r is PromiseRejectedResult => r.status === "rejected");
return rejected?.reason;
}
/**
* The sentence a batch's OWN confirmation draws when the batch did not all land, or `null` when
* it did.
*
* A partial failure used to be reported in a toast alone — the right words in the wrong place: a
* box that dismisses itself after six seconds and sits over the confirmation rather than in it,
* so the one thing the user needs while retrying is also the first thing to leave. The
* confirmation now keeps itself open on anything short of every target landing (see
* `ConfirmModal`'s `refusal` slot), and this is the sentence it draws there: the partial-failure
* line, which already names the targets that did not land, plus the first rejection's own words.
*
* The sentence stands on its own rather than behind `S.common.refused`'s "the operation was
* refused:" lead-in: a batch that wrote three of five was not refused, and the line already says
* what happened.
*/
export function bulkFailureText(
outcome: BulkOutcome,
reason: string,
sentence: (ok: number, failed: string) => string,
separator: string,
): string | null {
if (outcome.allOk) return null;
return `${sentence(outcome.ok, failedList(outcome.failed, separator))} — ${reason}`;
}
/**
* The part of a batch that is still behind: every target whose request was rejected, with the
* names left to rewrite recomputed from what remains.
*
* Handed back to the confirmation that asked for the batch, so its retry asks about exactly the
* targets the sentence named as not having landed. Re-running the whole plan instead would
* rewrite the ones that did take it — each one is an overwriting reinstall — and the count in
* the success line afterwards would be about attempts rather than about what was behind.
*/
export function remainingTargets<T extends { names: readonly string[] }>(
targets: readonly T[],
results: readonly PromiseSettledResult<unknown>[],
): { targets: T[]; names: string[] } {
// `allSettled` preserves input order, which is what makes the pairing sound — the same rule
// `bulkOutcome` reads its labels by.
const left = targets.filter((_, i) => results[i]?.status === "rejected");
const names = new Set<string>();
for (const target of left) for (const name of target.names) names.add(name);
return { targets: left, names: [...names].sort() };
}