@asrunjs/asrun 0.13.0 → 0.15.0

package/dist/lib/scaffold.d.ts

@@ -0,0 +1,87 @@
+import { type WorkspaceMarker } from './migrations.js';
+/**
+ * The files a workspace gets from the framework, and the baseline that says whether the project has aligned a
+ * project-owned file with the template of the release it now runs.
+ *
+ * `init` is the only writer of the files themselves; this module is also what the upgrade prompt and `doctor` read, so
+ * "which project files still need a person or an AI" is a computed answer rather than a guess. The baseline lives in
+ * `.asrun.json` (`scaffold`), so it travels with the repository: a clone sees exactly what the person who upgraded saw.
+ */
+/** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
+export declare const GENERATED: {
+    file: string;
+    template: string;
+}[];
+/** Files `init` creates once; after that the project owns them and may edit them freely. */
+export declare const ONCE: {
+    file: string;
+    template: string;
+}[];
+/** True for a file a release may only merge into, never replace. */
+export declare function isProjectData(file: string): boolean;
+/** How a workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
+export declare function frameworkPath(root: string): string;
+/** True when this workspace has the package installed (or is the framework's own checkout). */
+export declare function isInstalled(root: string): boolean;
+/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
+export declare function renderTemplate(name: string, root: string): string;
+/**
+ * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives
+ * inside the framework repository (examples/demo) has no `node_modules` of its own, so it points at the framework's.
+ * Kept relative: the file is committed and must not name a machine.
+ */
+export declare function playwrightBin(root: string): string;
+/** The version and commit of the framework that is installed (or of this checkout). */
+export declare function frameworkVersion(): {
+    version: string;
+    commit: string;
+};
+/** One entry of the scaffold baseline: the template the project file is known to be aligned with. */
+export interface ScaffoldRecord {
+    /** The release whose template the file was aligned with; `unknown` for a record written from an older marker. */
+    version: string;
+    /** sha256 (16 hex) of the rendered template at that release. */
+    template: string;
+}
+/**
+ * What an upgrade reports about one project-owned file.
+ *
+ * - `current`: the file equals the template of the installed release; nothing to do.
+ * - `aligned`: the project edited it, and it was confirmed aligned with this template (`init --ack` or a migration).
+ * - `replace`: nobody edited it and the template changed; `init --force <file>` is safe.
+ * - `merge`: both changed; a person or an AI merges the template's part and then confirms with `init --ack`.
+ * - `unknown-base`: no baseline (the workspace predates the baseline); compare the two by hand and report.
+ * - `missing`: the template has the file and the workspace does not.
+ */
+export type ScaffoldState = 'current' | 'aligned' | 'replace' | 'merge' | 'unknown-base' | 'missing';
+export interface ScaffoldDrift {
+    file: string;
+    state: ScaffoldState;
+    /** The template's hash at the installed release. */
+    templateHash: string;
+    /** The hash recorded in `.asrun.json`, or null when the workspace never recorded one. */
+    recordedHash: string | null;
+    /** True when the project changed the file away from the template it was created from. */
+    edited: boolean;
+    /** `profiles.yaml` / `package.json`: merge by hand, never replace. */
+    projectData: boolean;
+}
+/** A short, stable fingerprint of a rendered template: enough to tell "same" from "changed", never a secret. */
+export declare function templateHash(text: string): string;
+/** The scaffold baseline of a marker, tolerant of an older marker without one (or a hand-edited entry). */
+export declare function scaffoldRecords(marker: WorkspaceMarker | null): Record<string, ScaffoldRecord>;
+/**
+ * The state of every once-only file against the installed release's templates. Read-only: it never writes the marker,
+ * because `doctor` and the prompt must be safe to run at any time.
+ */
+export declare function scaffoldDrift(root: string, marker?: WorkspaceMarker | null): ScaffoldDrift[];
+/** The drift entries that still need somebody: everything except `current` and `aligned`. */
+export declare function outstandingDrift(drift: readonly ScaffoldDrift[]): ScaffoldDrift[];
+/**
+ * Records that these project files are aligned with the installed release's templates, without touching the files:
+ * what `init --ack <file>` and `migrate --ack <id>` (for the files its `files` names) do. A file that does not exist
+ * is skipped: `init --force <file>` is the command for a missing one.
+ */
+export declare function ackScaffold(root: string, files: readonly string[], version?: string): string[];
+/** The once-only files among a list of paths: what a migration's `files` may name and what an ack can advance. */
+export declare function scaffoldFiles(files: readonly string[]): string[];

package/dist/lib/scaffold.js

@@ -0,0 +1,220 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { FRAMEWORK_ROOT, PACKAGE, TEMPLATES_DIR, isRepoCheckout } from './paths.js';
+import { readMarker, updateMarker } from './migrations.js';
+/**
+ * The files a workspace gets from the framework, and the baseline that says whether the project has aligned a
+ * project-owned file with the template of the release it now runs.
+ *
+ * `init` is the only writer of the files themselves; this module is also what the upgrade prompt and `doctor` read, so
+ * "which project files still need a person or an AI" is a computed answer rather than a guess. The baseline lives in
+ * `.asrun.json` (`scaffold`), so it travels with the repository: a clone sees exactly what the person who upgraded saw.
+ */
+/** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
+export const GENERATED = [
+    { file: 'playwright.config.ts', template: 'playwright.config.ts' },
+    { file: 'tests/seed.spec.ts', template: 'seed.spec.ts' },
+    { file: '.claude/commands/make-case.md', template: '.claude/commands/make-case.md' },
+    { file: '.claude/commands/explore-case.md', template: '.claude/commands/explore-case.md' },
+    { file: '.claude/commands/gen-spec.md', template: '.claude/commands/gen-spec.md' },
+    { file: '.claude/commands/heal-spec.md', template: '.claude/commands/heal-spec.md' },
+    { file: '.claude/commands/upgrade-workspace.md', template: '.claude/commands/upgrade-workspace.md' },
+    // OpenCode does not read `.claude/commands` (only `.claude/skills`), so the same commands live here too.
+    { file: '.opencode/commands/make-case.md', template: '.claude/commands/make-case.md' },
+    { file: '.opencode/commands/explore-case.md', template: '.claude/commands/explore-case.md' },
+    { file: '.opencode/commands/gen-spec.md', template: '.claude/commands/gen-spec.md' },
+    { file: '.opencode/commands/heal-spec.md', template: '.claude/commands/heal-spec.md' },
+    { file: '.opencode/commands/upgrade-workspace.md', template: '.claude/commands/upgrade-workspace.md' },
+];
+/** Files `init` creates once; after that the project owns them and may edit them freely. */
+export const ONCE = [
+    { file: 'AGENTS.md', template: 'AGENTS.md' },
+    { file: 'CLAUDE.md', template: 'CLAUDE.md' },
+    { file: '.mcp.json', template: '.mcp.json' },
+    { file: 'opencode.jsonc', template: 'opencode.jsonc' },
+    { file: '.claude/settings.json', template: '.claude/settings.json' },
+    { file: 'tsconfig.json', template: 'tsconfig.json' },
+    { file: 'pnpm-workspace.yaml', template: 'pnpm-workspace.yaml' },
+    { file: 'profiles.yaml', template: 'profiles.yaml' },
+    { file: 'cases/_template.md', template: 'cases/_template.md' },
+    { file: 'package.json', template: 'package.json' },
+];
+/**
+ * The project's own data among the once-only files: a release never replaces it (`--force` refuses too), so a drift
+ * report says "merge by hand" instead of offering a command.
+ */
+const PROJECT_DATA = new Set(['profiles.yaml', 'package.json']);
+/** True for a file a release may only merge into, never replace. */
+export function isProjectData(file) {
+    return PROJECT_DATA.has(file);
+}
+/** How a workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
+export function frameworkPath(root) {
+    if (!isRepoCheckout()) {
+        // The standard install location, or a hoisted one in a monorepo.
+        for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
+            const candidate = path.join(dir, 'node_modules', PACKAGE);
+            if (fs.existsSync(path.join(candidate, 'package.json'))) {
+                const relative = path.relative(root, candidate).split(path.sep).join('/');
+                return relative.startsWith('.') ? relative : `./${relative}`;
+            }
+            if (path.dirname(dir) === dir)
+                break;
+        }
+        // Not installed yet (a scaffolding run): name the place the package will live.
+        return `./node_modules/${PACKAGE}`;
+    }
+    const relative = path.relative(root, FRAMEWORK_ROOT).split(path.sep).join('/');
+    if (relative === '')
+        return '.';
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
+/** True when this workspace has the package installed (or is the framework's own checkout). */
+export function isInstalled(root) {
+    return fs.existsSync(path.join(path.resolve(root), frameworkPath(root), 'package.json'));
+}
+/** The range the workspace's `package.json` names for the framework: `^` plus the version that wrote the workspace. */
+let asrunRange;
+function asrunDependencyRange() {
+    asrunRange ??= `^${frameworkVersion().version}`;
+    return asrunRange;
+}
+function readTemplate(name) {
+    return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
+}
+/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
+export function renderTemplate(name, root) {
+    return readTemplate(name)
+        .replaceAll('{{framework}}', frameworkPath(root))
+        .replaceAll('{{playwright}}', playwrightBin(root))
+        .replaceAll('{{asrun}}', asrunDependencyRange());
+}
+/**
+ * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives
+ * inside the framework repository (examples/demo) has no `node_modules` of its own, so it points at the framework's.
+ * Kept relative: the file is committed and must not name a machine.
+ */
+export function playwrightBin(root) {
+    if (fs.existsSync(path.join(root, 'node_modules', '.bin', 'playwright')))
+        return './node_modules/.bin/playwright';
+    const framework = frameworkPath(root);
+    return framework.startsWith('..') ? `${framework}/node_modules/.bin/playwright` : './node_modules/.bin/playwright';
+}
+/** The version and commit of the framework that is installed (or of this checkout). */
+export function frameworkVersion() {
+    let version = '0.0.0';
+    try {
+        version = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8')).version ?? version;
+    }
+    catch {
+        // keep the default
+    }
+    let commit = 'unknown';
+    try {
+        commit = spawnSync('git', ['-C', FRAMEWORK_ROOT, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8' }).stdout.trim() || 'unknown';
+    }
+    catch {
+        // keep the default
+    }
+    return { version, commit };
+}
+/** A short, stable fingerprint of a rendered template: enough to tell "same" from "changed", never a secret. */
+export function templateHash(text) {
+    // Line endings are not a change: a checkout on Windows may hold CRLF while init wrote LF.
+    return createHash('sha256').update(text.replace(/\r\n/g, '\n')).digest('hex').slice(0, 16);
+}
+/** The scaffold baseline of a marker, tolerant of an older marker without one (or a hand-edited entry). */
+export function scaffoldRecords(marker) {
+    const raw = marker?.scaffold;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const records = {};
+    for (const [file, value] of Object.entries(raw)) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const entry = value;
+        if (typeof entry.template !== 'string')
+            continue;
+        records[file] = { version: typeof entry.version === 'string' ? entry.version : 'unknown', template: entry.template };
+    }
+    return records;
+}
+/**
+ * The state of every once-only file against the installed release's templates. Read-only: it never writes the marker,
+ * because `doctor` and the prompt must be safe to run at any time.
+ */
+export function scaffoldDrift(root, marker = readMarker(root)) {
+    const records = scaffoldRecords(marker);
+    // The framework's own checkout (examples/demo) has no package-manager settings of its own, and init skips them
+    // there: reporting them as missing would nag every maintainer forever.
+    const checkout = frameworkPath(root).startsWith('..');
+    return ONCE.filter((entry) => !(checkout && (entry.file === 'pnpm-workspace.yaml' || entry.file === 'package.json'))).map((entry) => {
+        const file = path.join(root, entry.file);
+        const hash = templateHash(renderTemplate(entry.template, root));
+        const record = records[entry.file];
+        const projectData = isProjectData(entry.file);
+        const base = {
+            file: entry.file,
+            templateHash: hash,
+            recordedHash: record?.template ?? null,
+            projectData,
+        };
+        if (!fs.existsSync(file))
+            return { ...base, state: 'missing', edited: false };
+        const current = readFile(file);
+        if (current === null)
+            return { ...base, state: 'unknown-base', edited: false };
+        const currentHash = templateHash(current);
+        if (currentHash === hash)
+            return { ...base, state: 'current', edited: false };
+        if (record === undefined)
+            return { ...base, state: 'unknown-base', edited: true };
+        if (record.template === hash)
+            return { ...base, state: 'aligned', edited: true };
+        const edited = currentHash !== record.template;
+        return { ...base, state: edited ? 'merge' : 'replace', edited };
+    });
+}
+/** The drift entries that still need somebody: everything except `current` and `aligned`. */
+export function outstandingDrift(drift) {
+    return drift.filter((entry) => entry.state !== 'current' && entry.state !== 'aligned');
+}
+function readFile(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Records that these project files are aligned with the installed release's templates, without touching the files:
+ * what `init --ack <file>` and `migrate --ack <id>` (for the files its `files` names) do. A file that does not exist
+ * is skipped: `init --force <file>` is the command for a missing one.
+ */
+export function ackScaffold(root, files, version = frameworkVersion().version) {
+    const acknowledged = [];
+    updateMarker(root, (marker) => {
+        const records = scaffoldRecords(marker);
+        for (const relative of files) {
+            const entry = ONCE.find((candidate) => candidate.file === normalize(relative));
+            if (entry === undefined)
+                continue;
+            if (!fs.existsSync(path.join(root, entry.file)))
+                continue;
+            records[entry.file] = { version, template: templateHash(renderTemplate(entry.template, root)) };
+            acknowledged.push(entry.file);
+        }
+        marker.scaffold = records;
+    });
+    return acknowledged;
+}
+/** The once-only files among a list of paths: what a migration's `files` may name and what an ack can advance. */
+export function scaffoldFiles(files) {
+    return files.map(normalize).filter((file) => ONCE.some((entry) => entry.file === file));
+}
+function normalize(file) {
+    return file.split('\\').join('/').replace(/^\.\//, '');
+}

package/dist/lib/term.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Terminal output shared by the commands: ANSI colors that respect `NO_COLOR` / `FORCE_COLOR`, and one card for a
+ * message that must not be missed (the "what is still to do" block of an upgrade).
+ *
+ * A card keeps its frame and its label when there is no color (a pipe, a CI log, the UI job log), so the same text
+ * stands out there too; the color only makes it louder on a terminal.
+ */
+/**
+ * Whether ANSI colors belong on this stream: an interactive terminal, unless NO_COLOR or FORCE_COLOR says otherwise.
+ * `FORCE_COLOR` wins, so a smoke test can see the colored line in a captured log.
+ */
+export declare function useColor(stream: {
+    isTTY?: boolean;
+}): boolean;
+/** One ANSI-styled run, or the text untouched when colors are off. */
+export declare function paint(text: string, code: string, color: boolean): string;
+export interface CardRow {
+    /** The short left column: a file path, a migration id, a state. */
+    label: string;
+    /** The right column: what to do about it, or the command to run. Wrapped to the card. */
+    text: string;
+}
+export interface CardOptions {
+    /** The word in the badge, e.g. `NEXT`. Kept in English: it is a marker people learn to look for. */
+    label: string;
+    /** The first line of the body, in one sentence. */
+    title: string;
+    /** Two-column rows (file, then what to do), aligned on the left column. */
+    rows?: CardRow[];
+    /** Plain lines, indented, after the rows. */
+    lines?: string[];
+    /** ANSI colors on the stream the card goes to. */
+    color: boolean;
+}
+/** A framed block with a badge: the one thing a person must not scroll past. */
+export declare function card(options: CardOptions, width?: number | undefined): string;

package/dist/lib/term.js

@@ -0,0 +1,77 @@
+/**
+ * Terminal output shared by the commands: ANSI colors that respect `NO_COLOR` / `FORCE_COLOR`, and one card for a
+ * message that must not be missed (the "what is still to do" block of an upgrade).
+ *
+ * A card keeps its frame and its label when there is no color (a pipe, a CI log, the UI job log), so the same text
+ * stands out there too; the color only makes it louder on a terminal.
+ */
+/**
+ * Whether ANSI colors belong on this stream: an interactive terminal, unless NO_COLOR or FORCE_COLOR says otherwise.
+ * `FORCE_COLOR` wins, so a smoke test can see the colored line in a captured log.
+ */
+export function useColor(stream) {
+    const force = (process.env.FORCE_COLOR ?? '').trim().toLowerCase();
+    if (force !== '' && force !== '0' && force !== 'false')
+        return true;
+    const noColor = (process.env.NO_COLOR ?? '').trim();
+    if (noColor !== '')
+        return false;
+    return stream.isTTY === true;
+}
+/** One ANSI-styled run, or the text untouched when colors are off. */
+export function paint(text, code, color) {
+    return color ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+/** The width a card is drawn at: the terminal's, kept between 60 and 100 so it reads on a wide and a narrow window. */
+function cardWidth(columns) {
+    const width = columns ?? 80;
+    return Math.max(60, Math.min(100, width));
+}
+/** A block of text wrapped to the card and indented, so a long path or sentence cannot break the frame. */
+function wrap(text, room) {
+    const lines = [];
+    for (const paragraph of text.split('\n')) {
+        if (paragraph.trim() === '') {
+            lines.push('');
+            continue;
+        }
+        let current = '';
+        for (const word of paragraph.trim().split(/\s+/)) {
+            if (current === '')
+                current = word;
+            else if (current.length + 1 + word.length <= room)
+                current += ` ${word}`;
+            else {
+                lines.push(current);
+                current = word;
+            }
+        }
+        if (current !== '')
+            lines.push(current);
+    }
+    return lines;
+}
+/** A framed block with a badge: the one thing a person must not scroll past. */
+export function card(options, width = process.stdout.columns) {
+    const columns = cardWidth(width);
+    const rule = paint('─'.repeat(columns), '1;33', options.color);
+    const badge = paint(` ${options.label} `, '43;30;1', options.color);
+    const out = [rule, `${badge} ${paint(options.title, '1', options.color)}`];
+    const rows = options.rows ?? [];
+    if (rows.length > 0 || (options.lines ?? []).length > 0)
+        out.push('');
+    const labelWidth = rows.reduce((widest, row) => Math.max(widest, row.label.length), 0);
+    for (const row of rows) {
+        const head = `  ${row.label.padEnd(labelWidth)}  `;
+        const [first, ...more] = wrap(row.text, columns - head.length);
+        out.push(`${head}${first ?? ''}`);
+        for (const line of more)
+            out.push(`${' '.repeat(head.length)}${line}`);
+    }
+    for (const line of options.lines ?? []) {
+        for (const wrapped of wrap(line, columns - 2))
+            out.push(wrapped === '' ? '' : `  ${wrapped}`);
+    }
+    out.push(rule);
+    return out.join('\n');
+}

package/dist/lib/update-check.d.ts

@@ -1,3 +1,4 @@
+export { useColor } from './term.js';
 export declare const CACHE_FILE: string;
 /** Development only: a hand-written answer, so the notice can be seen without publishing a release. */
 export declare const MOCK_FILE: string;
@@ -31,13 +32,6 @@ export declare function checkForUpdate(options?: {
 }): UpdateStatus;
 /** The command that moves this installation to the newest release. */
 export declare function upgradeCommand(kind: InstallKind): string;
-/**
- * Whether ANSI colors belong on this stream: an interactive terminal, unless NO_COLOR or FORCE_COLOR says otherwise.
- * `FORCE_COLOR` wins, so a smoke test can see the colored line in a captured log.
- */
-export declare function useColor(stream: {
-    isTTY?: boolean;
-}): boolean;
 /**
  * The one-line notice, or null when there is nothing to say. `color` adds a badge and highlights the version and the
  * command, for a person looking at a terminal; the API and a piped log keep the plain sentence.

package/dist/lib/update-check.js

@@ -2,7 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { compareVersions, isVersion } from './migrations.js';
 import { FRAMEWORK_ROOT, PACKAGE, TMP_DIR, isRepoCheckout } from './paths.js';
+import { paint, useColor } from './term.js';
 import { releaseInfo } from './registry.js';
+// Kept here for the callers that had it from this module before the terminal helpers moved to `term.ts`.
+export { useColor } from './term.js';
 /**
  * Is a newer release of the framework on the registry? The command line asks before every command and the web UI asks
  * once at startup and once a day; both read the same cache in `.tmp/`, so the registry is asked at most once a day per
@@ -173,21 +176,6 @@ export function checkForUpdate(options = {}) {
 export function upgradeCommand(kind) {
     return kind === 'checkout' ? 'git pull' : 'pnpm asrun upgrade';
 }
-/**
- * Whether ANSI colors belong on this stream: an interactive terminal, unless NO_COLOR or FORCE_COLOR says otherwise.
- * `FORCE_COLOR` wins, so a smoke test can see the colored line in a captured log.
- */
-export function useColor(stream) {
-    const force = (process.env.FORCE_COLOR ?? '').trim().toLowerCase();
-    if (force !== '' && force !== '0' && force !== 'false')
-        return true;
-    const noColor = (process.env.NO_COLOR ?? '').trim();
-    if (noColor !== '')
-        return false;
-    return stream.isTTY === true;
-}
-/** One ANSI-styled run, or the text untouched when colors are off. */
-const paint = (text, code, color) => (color ? `\u001b[${code}m${text}\u001b[0m` : text);
 /**
  * The one-line notice, or null when there is nothing to say. `color` adds a badge and highlights the version and the
  * command, for a person looking at a terminal; the API and a piped log keep the plain sentence.

package/dist/lib/upgrade-prompt.d.ts

@@ -0,0 +1,84 @@
+import { type WorkspaceMarker } from './migrations.js';
+import { type ScaffoldDrift } from './scaffold.js';
+import { type CardRow } from './term.js';
+/**
+ * What an upgrade leaves to a person or an AI, and the prompt that hands it over.
+ *
+ * One prompt, version-independent: the procedure (read the rules, merge the scaffold text, run the checks, never touch
+ * what a case asserts) is the same for every release, and the release-specific part is data — which migrations are
+ * outstanding and which project files the templates moved under. A workspace that has nothing to do gets a short
+ * prompt, so nobody spends an AI run on a patch release.
+ */
+/** One migration that still needs somebody, with the acknowledgement command that clears it. */
+export interface OutstandingMigration {
+    id: string;
+    version: string;
+    summary: string;
+    details?: string;
+    manual: string[];
+    files: string[];
+    /** The command that records the manual steps as done; printed with the real id, never as `<id>`. */
+    ack: string;
+}
+/** A project file whose template changed (or which has no baseline yet), with the command that resolves it. */
+export interface OutstandingFile {
+    file: string;
+    state: ScaffoldDrift['state'];
+    /** What to do, in one sentence. */
+    action: string;
+    /** The command to run once the action is done; null when only the project can decide. */
+    command: string | null;
+    projectData: boolean;
+}
+export interface UpgradeOutstanding {
+    drift: ScaffoldDrift[];
+    files: OutstandingFile[];
+    migrations: OutstandingMigration[];
+    /** Migrations this workspace has not applied yet (`pnpm asrun migrate` runs them). */
+    pending: number;
+}
+export interface UpgradePromptPayload {
+    workspace: string;
+    /** The framework as the workspace reaches it (a path relative to the workspace). */
+    framework: string;
+    /** `installed` for a package from the registry, `checkout` for the framework's own git checkout. */
+    kind: 'installed' | 'checkout';
+    /** The release the workspace came from, when `.asrun.json` still remembers it. */
+    from: string | null;
+    /** The release the workspace runs now. */
+    to: string;
+    drift: ScaffoldDrift[];
+    files: OutstandingFile[];
+    migrations: OutstandingMigration[];
+    pending: number;
+    /** The commands that end the work, in the order a person should run them. */
+    acks: Array<{
+        id: string;
+        command: string;
+    }>;
+    /** The checks the agent runs, in order; the same list in the prompt. */
+    checks: string[];
+    /** The prompt itself, ready to paste into an agent. */
+    prompt: string;
+}
+/** Everything an upgrade still leaves open, computed from the marker, the registry and the installed templates. */
+export declare function upgradeOutstanding(root: string, marker?: WorkspaceMarker | null): UpgradeOutstanding;
+/** True when an upgrade leaves nothing for a person or an AI to do. */
+export declare function nothingToDo(outstanding: UpgradeOutstanding): boolean;
+/**
+ * The rows of the "NEXT" card: one per file or migration, each with the exact command. A person must be able to finish
+ * the upgrade by copying from here, without reading the prompt or the docs.
+ */
+export declare function nextStepRows(outstanding: UpgradeOutstanding): CardRow[];
+/** One sentence for the title of the card, so the count and the work agree. */
+export declare function nextStepTitle(outstanding: UpgradeOutstanding): string;
+/** The payload and the prompt of one workspace, ready for the command line and for the web UI. */
+export declare function upgradePrompt(root: string): UpgradePromptPayload;
+/**
+ * The framed "what is left" block, or null when the workspace has nothing outstanding. It carries the exact commands and
+ * names the recommended way to have an agent do them, so a person never has to remember a flag or an id.
+ */
+export declare function nextStepsText(root: string, options: {
+    color: boolean;
+    width?: number;
+}): string | null;