@asrunjs/asrun 0.12.0 → 0.14.0

package/dist/lib/paths.d.ts

@@ -30,7 +30,14 @@ export declare const EXPLORE_DIR: string;
 export declare const TEMPLATES_DIR: string;
 export declare const SKILLS_DIR: string;
 /**
- * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
- * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ * The folder of a package the framework needs at run time: the framework's own dependency, or the workspace's (a
+ * hoisted or linked install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use
+ * this.
+ *
+ * Node's own resolution comes first, because it is the same one every `import` in this package goes through: the
+ * folder and the module that is loaded can then never disagree. A hand-built path could not promise that — under
+ * pnpm's virtual store the framework sits in `<store>/node_modules/@asrunjs/asrun`, so the folder that holds its
+ * dependencies is one `node_modules`, not two, and appending a second one named the wrong folder and made every PDF
+ * check fail with "pdfjs-dist is not installed" while the package was installed.
  */
 export declare function packageDir(packageName: string): string;

package/dist/lib/paths.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 /**
  * Where the framework's own code and assets live: the package folder (`node_modules/@asrunjs/asrun`). The compiled files sit in
  * `dist/lib`, so one level up from there is the package root again.
@@ -87,13 +88,39 @@ export const EXPLORE_DIR = path.join(ROOT, '.explore');
 export const TEMPLATES_DIR = path.join(FRAMEWORK_ROOT, 'templates');
 export const SKILLS_DIR = path.join(FRAMEWORK_ROOT, '.claude', 'skills');
 /**
- * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
- * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ * The folder of a package the framework needs at run time: the framework's own dependency, or the workspace's (a
+ * hoisted or linked install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use
+ * this.
+ *
+ * Node's own resolution comes first, because it is the same one every `import` in this package goes through: the
+ * folder and the module that is loaded can then never disagree. A hand-built path could not promise that — under
+ * pnpm's virtual store the framework sits in `<store>/node_modules/@asrunjs/asrun`, so the folder that holds its
+ * dependencies is one `node_modules`, not two, and appending a second one named the wrong folder and made every PDF
+ * check fail with "pdfjs-dist is not installed" while the package was installed.
  */
 export function packageDir(packageName) {
-    // The package's own install, the pnpm virtual store that holds its dependencies, or a hoisted install in the workspace.
-    for (const base of [FRAMEWORK_ROOT, path.dirname(path.dirname(FRAMEWORK_ROOT)), ROOT]) {
-        const dir = path.join(base, 'node_modules', packageName);
+    // A bare name resolves to the package's entry point only; asking for the manifest is the portable way to its folder.
+    try {
+        const dir = path.dirname(createRequire(import.meta.url).resolve(`${packageName}/package.json`));
+        if (fs.existsSync(path.join(dir, 'package.json')))
+            return dir;
+    }
+    catch {
+        // Not resolvable from here (an `exports` map without "./package.json", or a package installed elsewhere): the
+        // folders that can hold an install answer instead.
+    }
+    // pnpm's virtual store already keeps a package's dependencies inside a `node_modules`, next to its scope folder;
+    // every other layout nests that folder inside the install root.
+    const store = path.dirname(path.dirname(FRAMEWORK_ROOT));
+    const candidates = [
+        // This package's own nested dependencies (an install strategy that nests instead of hoisting).
+        path.join(FRAMEWORK_ROOT, 'node_modules', packageName),
+        // The dependencies next to it: pnpm's store, or the root of a hoisted install.
+        path.basename(store) === 'node_modules' ? path.join(store, packageName) : path.join(store, 'node_modules', packageName),
+        // The workspace's own install: a peer dependency (`@playwright/test`) lives here.
+        path.join(ROOT, 'node_modules', packageName),
+    ];
+    for (const dir of candidates) {
         if (fs.existsSync(dir))
             return dir;
     }

package/dist/lib/pdf.js

@@ -1,13 +1,33 @@
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { createCanvas } from '@napi-rs/canvas';
 import { expect } from '@playwright/test';
 import { packageDir } from './paths.js';
 let pdfjs;
-const loadPdfjs = () => (pdfjs ??= import('pdfjs-dist/legacy/build/pdf.mjs'));
-// pdf.js loads its fonts, cmaps and wasm files from the package folder, not from the consuming project.
+const loadPdfjs = () => (pdfjs ??= import('pdfjs-dist/legacy/build/pdf.mjs').catch((error) => {
+    // The one dependency of this module. A raw ERR_MODULE_NOT_FOUND names this file and nothing a person can act on.
+    throw new Error(`The PDF renderer is unavailable: "pdfjs-dist" could not be loaded (${error.message}). The asrun install is ` +
+        'incomplete: run "pnpm install" in the workspace root, or install the framework again ("pnpm add -D ' +
+        '@asrunjs/asrun"). "pnpm asrun doctor" says which part is missing.');
+}));
+// pdf.js loads its fonts, cmaps and wasm files from the package folder, not from the consuming project. The folder is
+// derived from the very module that is imported, so it cannot drift from the code that reads it: a hand-built path was
+// one `node_modules` too deep under pnpm's virtual store, and every PDF check failed although the package was there.
+// `packageDir` answers only when the module itself cannot be resolved (then the load above reports it).
 let pdfjsDir;
-const dirUrl = (dir) => pathToFileURL(path.join((pdfjsDir ??= packageDir('pdfjs-dist')), dir)).href + '/';
+function pdfjsRoot() {
+    if (pdfjsDir !== undefined)
+        return pdfjsDir;
+    try {
+        const build = createRequire(import.meta.url).resolve('pdfjs-dist/legacy/build/pdf.mjs');
+        return (pdfjsDir = path.resolve(path.dirname(build), '..', '..'));
+    }
+    catch {
+        return (pdfjsDir = packageDir('pdfjs-dist'));
+    }
+}
+const dirUrl = (dir) => pathToFileURL(path.join(pdfjsRoot(), dir)).href + '/';
 /** A corner of the page. Defaults: 30% of the width and 12% of the height, enough for a logo and nothing else. */
 export function corner(name, size = {}) {
     const width = size.width ?? 0.3;

package/dist/scripts/check-cases.js

@@ -58,7 +58,7 @@ function questionProblems(id) {
             warnings.push(`the "✍️ Answer:" line of the question on line ${question.line} is not the last line of its block`);
         }
         if (!question.parent) {
-            warnings.push(`the question on line ${question.line} has no text above it: accepting it would delete a claim nobody sees`);
+            warnings.push(`the question on line ${question.line} has no sentence it is about: accepting it would delete a claim nobody sees`);
             continue;
         }
         const step = doc.steps.find((candidate) => candidate.line === question.parent?.line);
@@ -67,8 +67,8 @@ function questionProblems(id) {
         }
         const anchor = immediateAnchor(splitLines(doc.text), question.line, question.indent);
         if (anchor !== null && anchor !== question.parent.line) {
-            const above = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
-            warnings.push(`the question on line ${question.line} hangs under "${above.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the text above it; indent it under that sentence or lift that sentence to a top-level bullet`);
+            const anchorText = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
+            warnings.push(`the question on line ${question.line} hangs under "${anchorText.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the sentence it is about; indent it under that sentence or lift that sentence to a top-level bullet`);
         }
     }
     for (const step of doc.steps) {

package/dist/scripts/cli.js

@@ -44,13 +44,18 @@ async function main() {
         await import('./explore-notes.js');
         return;
     }
+    if (command === 'notify-test') {
+        const { main: notifyTest } = await import('./notify-test.js');
+        process.exitCode = await notifyTest(rest);
+        return;
+    }
     if (command === 'help' || command === '--help-init') {
         console.log(USAGE);
         return;
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explore:notes] [options]
+const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explore:notes|notify-test] [options]
 
   (no subcommand)  Run the tests of one environment. See "pnpm asrun --help".
   init             Create the files a workspace needs (never overwrites; --update refreshes generated files,
@@ -65,5 +70,7 @@ const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explor
                    target release for breaking changes (see "pnpm asrun upgrade --help").
   migrate          Apply the workspace migrations of the installed release, or list them (see "pnpm asrun migrate
                    --help"). "upgrade" runs it; use it after a manual install.
-  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").`;
+  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").
+  notify-test      Show one desktop notification and print the command behind it, to tell a hidden notification from a
+                   broken one (see "pnpm asrun notify-test --help").`;
 await main();

package/dist/scripts/doctor.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
-import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
+import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR, packageDir } from '../lib/paths.js';
 import { readWorkspaceConfig } from '../lib/config.js';
 import { readProjectRules, mentionedTestDataPrefixes } from '../lib/rules.js';
 import { spawnTarget } from '../lib/command.js';
@@ -85,6 +85,33 @@ function documentedBrowserTools() {
     const section = /^## Runnable\n([\s\S]*?)^## /m.exec(text)?.[1] ?? '';
     return [...new Set(section.match(/browser_[a-z0-9_]+/g) ?? [])];
 }
+/**
+ * The PDF renderer, which is how an exploring agent looks at a downloaded PDF and how a spec checks one: `lib/pdf.js`
+ * imports `pdfjs-dist` and `@napi-rs/canvas` at run time, and pdf.js reads its fonts and cmaps from the package folder
+ * `packageDir` names. Both are runtime dependencies of the framework, so a failure means the install (or the Node
+ * version) is broken — and it used to surface only when someone rendered a PDF, halfway through an exploration.
+ */
+async function pdfRenderer() {
+    let dir;
+    try {
+        dir = packageDir('pdfjs-dist');
+    }
+    catch {
+        // `packageDir` already says where it looked; the caller adds what to do about it.
+        return { ok: false, reason: 'pdfjs-dist is not installed where the framework can reach it' };
+    }
+    try {
+        const version = JSON.parse(read(path.join(dir, 'package.json')) ?? '{}').version ?? 'unknown';
+        // Loading both is what proves it: the module import resolves exactly like the one in `lib/pdf.js`, and the native
+        // canvas is what draws the page.
+        await import('pdfjs-dist/legacy/build/pdf.mjs');
+        await import('@napi-rs/canvas');
+        return { ok: true, version };
+    }
+    catch (error) {
+        return { ok: false, reason: error.message };
+    }
+}
 export async function main(args) {
     if (args.includes('--help')) {
         console.log('Usage: pnpm asrun doctor');
@@ -296,6 +323,17 @@ export async function main(args) {
         warnings.push(`${extra.pkg} is not installed and this machine does not provide it: ${extra.provides} is skipped. Run ` +
             '"pnpm asrun init" (or "pnpm go") to install it, or install the tool yourself and run doctor again.');
     }
+    // The PDF renderer: "pnpm pdf:render", the exploring agent's look at a downloaded PDF, and every `expectPdf` check.
+    const pdf = await pdfRenderer();
+    if (pdf.ok) {
+        facts.push(`pdf renderer:  pdfjs-dist ${pdf.version} (canvas ok)`);
+    }
+    else {
+        // An Error message may already end with a period; the sentence around it must not double it.
+        const reason = pdf.reason.replace(/\.\s*$/, '');
+        errors.push(`The PDF renderer does not work, so "pnpm pdf:render" and every PDF check fail (${reason}). To fix it, run ` +
+            '"pnpm install" in the workspace root (Node 22.13 or newer is required), or install the framework again.');
+    }
     let scripts = null;
     try {
         const packageJson = read(path.join(ROOT, 'package.json'));

package/dist/scripts/notify-test.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): Promise<number>;

package/dist/scripts/notify-test.js

@@ -0,0 +1,48 @@
+import { describeCommand, notificationCommand, sendNotification } from '../lib/desktop-notify.js';
+/*
+ * `pnpm asrun notify-test`
+ *
+ * Shows one desktop notification through the same module the UI server notifies with, and prints what it ran. The
+ * point is to separate "the code is wrong" from "this machine hides notifications": a notification that never appears
+ * while this command exits 0 means the operating system dropped it, and the hint below says where to look.
+ */
+const USAGE = `Usage: pnpm asrun notify-test [--help]
+
+  Shows one desktop notification and prints the command that showed it. Nothing is written to a case or a report.
+
+  Use it when "your turn" produced no notification: the UI server sends those through the same command.
+  macOS:    System Settings > Notifications > the app that runs this (Terminal, iTerm2, ...).
+  Windows:  Settings > System > Notifications, and turn off Focus assist while you test.
+  Linux:    install libnotify (the "notify-send" command).`;
+const HINT = {
+    darwin: 'If nothing appeared, the system dropped it: open System Settings > Notifications, find the app that runs this ' +
+        'command (Terminal, iTerm2, the editor you run pnpm in) and allow notifications for it. Focus mode hides them too.',
+    win32: 'If nothing appeared, check Settings > System > Notifications (and Focus assist), and that a notification banner is ' +
+        'not turned off for Windows PowerShell.',
+    linux: 'If nothing appeared, install libnotify (the "notify-send" command) and check that a notification daemon runs in ' +
+        'this session.',
+};
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const notification = {
+        title: 'AsRun — test',
+        body: 'A desktop notification: this is how "your turn in the browser window" reaches you.',
+        sound: true,
+    };
+    const command = notificationCommand(process.platform, notification);
+    if (command)
+        console.log(`Running: ${describeCommand(command)}`);
+    const outcome = await sendNotification(notification);
+    if (outcome.ok) {
+        console.log('Done: a notification should be on screen now. If it is not, the system dropped it, not asrun.');
+        return 0;
+    }
+    console.error(`No notification: ${outcome.reason ?? 'the command failed'}`);
+    const hint = HINT[process.platform];
+    if (hint)
+        console.error(hint);
+    return 1;
+}

package/dist/ui/server/actions.js

@@ -259,8 +259,10 @@ export function buildJobSpec(request) {
             thinking: request.thinking,
             force: request.force,
             attended: request.attended,
-            // Naming every profile of the environment is the same as leaving it out: the agent then takes all that are logged in.
-            profiles: request.profiles && request.profiles.length < profilesInEnv.length ? request.profiles : undefined,
+            // Always the picked ids, even when they name every profile of the environment: without the flag explore falls back
+            // to one logged-in profile per domain, which is not the same as "the profiles you ticked". Heal runs only the
+            // profiles that are logged in anyway.
+            profiles: request.profiles,
             hints: hintsPath,
             report: request.report,
         };

package/dist/ui/server/ai-stream.d.ts

@@ -13,6 +13,8 @@ export interface LogPart {
 /** The agent has put a handoff card in the browser window and waits for the person (see user-handoff.md). */
 export interface AwaitingUser {
     message: string | null;
+    /** The finish condition the card shows in its "DONE WHEN" block; null when the options did not name one. */
+    finish: string | null;
     since: number;
 }
 export declare class AiStreamFormatter {
@@ -21,8 +23,12 @@ export declare class AiStreamFormatter {
     private pending;
     private cardCalls;
     private waitingForUser;
-    /** The message of the last options call, kept so a card that runs after unrelated calls still carries it. */
+    /**
+     * The message and finish condition of the last options call, kept so a card that runs after unrelated calls still
+     * carries them.
+     */
     private lastHandoffMessage;
+    private lastHandoffFinish;
     private lastEventAt;
     private lastWaitAt;
     /** The last call the agent finished, so a quiet spell can say what it is doing instead of only that nothing came. */
@@ -53,8 +59,8 @@ export declare class AiStreamFormatter {
     /** A call the agent has started and not finished yet (Claude reports both ends). */
     private start;
     /**
-     * The end of a call, plus the first lines of what it returned. `fallback` is for a CLI that reports a call only when
-     * it is over (OpenCode), which still knows when it started.
+     * The end of a call, plus what it returned. `fallback` is for a CLI that reports a call only when it is over
+     * (OpenCode), which still knows when it started.
      */
     private finishCall;
     /** Said once per run, after the first tool call that Claude Code's sandbox refused (nobody is there to approve it). */