burgee 0.7.1 → 0.8.0

package/dist/commander/error.js

@@ -1,4 +1,3 @@
-/** commander's error classes, byte-for-byte in shape: `code`, `exitCode`, `nestedError`. */
 export class CommanderError extends Error {
     code;
     exitCode;
@@ -19,4 +18,3 @@ export class InvalidArgumentError extends CommanderError {
         this.name = this.constructor.name;
     }
 }
-//# sourceMappingURL=error.js.map

package/dist/commander/help.js

@@ -1,13 +1,11 @@
 import { stripVTControlCharacters } from 'node:util';
 import { humanReadableArgName } from './argument.js';
-/** Methods are static in style so a subclass, or plain functions via `configureHelp`, can override them. */
 export class Help {
     helpWidth = undefined;
     minWidthToWrap = 40;
     sortSubcommands = false;
     sortOptions = false;
     showGlobalOptions = false;
-    /** Called after `configureHelp` overrides are applied and just before `formatHelp`. */
     prepareContext(contextOptions) {
         this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
     }
@@ -28,7 +26,6 @@ export class Help {
         const visibleOptions = cmd.options.filter((option) => !option.hidden);
         const helpOption = cmd._getHelpOption();
         if (helpOption && !helpOption.hidden) {
-            // Historical: hide the built-in help flags a user option already took.
             const removeShort = helpOption.short && cmd._findOption(helpOption.short);
             const removeLong = helpOption.long && cmd._findOption(helpOption.long);
             if (!removeShort && !removeLong)
@@ -54,7 +51,6 @@ export class Help {
         return globalOptions;
     }
     visibleArguments(cmd) {
-        // Side effect: apply the legacy descriptions before the arguments are displayed.
         if (cmd._argsDescription) {
             for (const argument of cmd.registeredArguments) {
                 argument.description = argument.description || cmd._argsDescription[argument.name()] || '';
@@ -110,7 +106,6 @@ export class Help {
     commandDescription(cmd) {
         return cmd.description();
     }
-    /** Summary, falling back to description for backwards compatibility. */
     subcommandDescription(cmd) {
         return cmd.summary() || cmd.description();
     }
@@ -120,7 +115,6 @@ export class Help {
             extraInfo.push(`choices: ${option.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`);
         }
         if (option.defaultValue !== undefined) {
-            // Defaults for boolean and negated are more for the programmer than the end user.
             const showDefault = option.required || option.optional || (option.isBoolean() && typeof option.defaultValue === 'boolean');
             if (showDefault)
                 extraInfo.push(`default: ${option.defaultValueDescription || JSON.stringify(option.defaultValue)}`);
@@ -154,7 +148,6 @@ export class Help {
             return [];
         return [helper.styleTitle(heading), ...items, ''];
     }
-    /** Groups in order of first appearance among all items; members in order of the visible items. */
     groupItems(unsortedItems, visibleItems, getGroup) {
         const result = new Map();
         for (const item of unsortedItems) {
@@ -203,7 +196,6 @@ export class Help {
         }
         return output.join('\n');
     }
-    /** Width ignoring ANSI escapes, for padding and wrapping. */
     displayWidth(str) {
         return stripVTControlCharacters(str).length;
     }
@@ -211,7 +203,6 @@ export class Help {
         return str;
     }
     styleUsage(str) {
-        // Assume the default usage shape: command subcommand [options] [command] <foo> [bar]
         return str
             .split(' ')
             .map((word) => {
@@ -273,15 +264,9 @@ export class Help {
     padWidth(cmd, helper) {
         return Math.max(helper.longestOptionTermLength(cmd, helper), helper.longestGlobalOptionTermLength(cmd, helper), helper.longestSubcommandTermLength(cmd, helper), helper.longestArgumentTermLength(cmd, helper));
     }
-    /** Manually wrapped text: a line break followed by whitespace. */
     preformatted(str) {
         return /\n[^\S\r\n]/.test(str);
     }
-    /**
-     * Pad the term and wrap the description, indenting the following lines:
-     *   TTT  DDD DDDD
-     *        DD DDD
-     */
     formatItem(term, termWidth, description, helper) {
         const itemIndent = 2;
         const itemIndentStr = ' '.repeat(itemIndent);
@@ -301,7 +286,6 @@ export class Help {
         }
         return itemIndentStr + paddedTerm + ' '.repeat(spacerWidth) + formattedDescription.replace(/\n/g, `\n${itemIndentStr}`);
     }
-    /** Wrap at whitespace, preserving existing line breaks; skipped below `minWidthToWrap`. */
     boxWrap(str, width) {
         if (width < this.minWidthToWrap)
             return str;
@@ -333,4 +317,3 @@ export class Help {
         return wrappedLines.join('\n');
     }
 }
-//# sourceMappingURL=help.js.map

package/dist/commander/option.js

@@ -1,4 +1,3 @@
-import {} from './argument.js';
 import { InvalidArgumentError } from './error.js';
 export class Option {
     flags;
@@ -25,7 +24,6 @@ export class Option {
         this.description = description || '';
         this.required = flags.includes('<');
         this.optional = flags.includes('[');
-        // `<value,...>` describes custom splitting of one argument, not a variadic option.
         this.variadic = /\w\.\.\.[>\]]$/.test(flags);
         const { shortFlag, longFlag } = splitOptionFlags(flags);
         this.short = shortFlag;
@@ -38,7 +36,6 @@ export class Option {
         this.defaultValueDescription = description;
         return this;
     }
-    /** Value used when the option appears without an option-argument. `parseArg` still runs. */
     preset(arg) {
         this.presetArg = arg;
         return this;
@@ -47,7 +44,6 @@ export class Option {
         this.conflictsWith = this.conflictsWith.concat(names);
         return this;
     }
-    /** Values implied for other options when this one is set and they are not. `parseArg` does not run on them. */
     implies(impliedOptionValues) {
         const newImplied = typeof impliedOptionValues === 'string' ? { [impliedOptionValues]: true } : impliedOptionValues;
         this.implied = Object.assign(this.implied ?? {}, newImplied);
@@ -90,7 +86,6 @@ export class Option {
             return this.long.replace(/^--/, '');
         return (this.short ?? '').replace(/^-/, '');
     }
-    /** camelCase key used on the options object; `--no-foo` shares `foo` with `--foo`. */
     attributeName() {
         return camelcase(this.negate ? this.name().replace(/^no-/, '') : this.name());
     }
@@ -101,15 +96,10 @@ export class Option {
     is(arg) {
         return this.short === arg || this.long === arg;
     }
-    /** Options are one of boolean, negated, required-argument or optional-argument. */
     isBoolean() {
         return !this.required && !this.optional && !this.negate;
     }
 }
-/**
- * `--build` and `--no-build` share one value. This works out which of the pair a
- * value (probably) came from, so implied values are only applied for the right one.
- */
 export class DualOptions {
     positiveOptions = new Map();
     negativeOptions = new Map();
@@ -135,7 +125,6 @@ export class DualOptions {
 function camelcase(str) {
     return str.split('-').reduce((acc, word) => acc + (word[0] ?? '').toUpperCase() + word.slice(1));
 }
-/** Split `'-m,--mixed <value>'` into its short and long flags, failing noisily on anything else. */
 export function splitOptionFlags(flags) {
     let shortFlag;
     let longFlag;
@@ -147,10 +136,8 @@ export function splitOptionFlags(flags) {
         shortFlag = flagParts.shift();
     if (longFlagExp.test(head()))
         longFlag = flagParts.shift();
-    // Long then short. Rarely used but fine.
     if (!shortFlag && shortFlagExp.test(head()))
         shortFlag = flagParts.shift();
-    // Two long flags, like '--ws, --workspace': the supported way to have a shortish flag.
     if (!shortFlag && longFlagExp.test(head())) {
         shortFlag = longFlag;
         longFlag = flagParts.shift();
@@ -175,4 +162,3 @@ export function splitOptionFlags(flags) {
     }
     return { shortFlag, longFlag };
 }
-//# sourceMappingURL=option.js.map

package/dist/compat.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A7 — the graded pass rate per host, as `burgee migrate` reports it.
+ *
+ * These are `compat-oracle`'s own numbers: the incumbent's test suite, vendored and run
+ * against burgee's front-end, which is what "drop-in" means here and the only claim in the
+ * package that is measured rather than argued.
+ *
+ * **They live here as a data module rather than as a literal in the report**, and
+ * `compat-baseline-lock.test.ts` holds this file equal to
+ * `packages/compat-oracle/baseline/<host>.json` — the same files the compat page renders.
+ * Changing a number here without the measurement moving fails that lock, which is the
+ * whole point: a number typed into a report template is a number that goes stale silently,
+ * and this repository has published four of those and caught them all late.
+ *
+ * It cannot be read from the oracle at run time. `compat-oracle` is `private: true` and is
+ * never published, so a user who installs `burgee` has no baseline directory to read; a
+ * copy with a lock on it is the strongest control available on the published side, and the
+ * lock is what makes it a copy rather than a claim.
+ */
+/** One row of the baseline, in the shape `baseline/<host>.json` stores it. */
+export interface Graded {
+    /** Cases in the incumbent's own suite. */
+    reference: number;
+    /** Cases that pass against burgee's front-end. */
+    passed: number;
+    /** `passed / reference`, carried rather than recomputed so it is the oracle's own division. */
+    rate: number;
+}
+/** The two hosts `migrate` rewrites, and nothing else — a row here without a mapping would claim a path that does not exist. */
+export declare const GRADED: Readonly<Record<string, Graded>>;

package/dist/compat.js

@@ -0,0 +1,4 @@
+export const GRADED = {
+    commander: { reference: 1360, passed: 1360, rate: 1 },
+    yargs: { reference: 804, passed: 804, rate: 1 },
+};

package/dist/definition.d.ts

@@ -26,11 +26,20 @@ import { type OptionSpec } from './manifest.js';
 export declare const WITHHELD = "withheld";
 /**
  * What must be true of a declaration before anything runs (yargs #1198, #887, #1679):
- * a known type, one short alias per command, no two keys that meet on the command line.
+ * a known type, one short alias per command, no two keys that meet on the command line, and
+ * none of V5's reserved surfaces.
+ *
+ * The reserved names used to be a second loop over the same keys in {@link checkCommand},
+ * and the numeric bound used to be a fourth branch in this one. Both moved to pay for the
+ * canonical-key check below without raising a weight ceiling — `./plugin` had 5 bytes of
+ * headroom — and both are better where they are now: `flag` is computed once here and
+ * `kebab` is the identity on every reserved name, and a numeric bound is a fact about a
+ * spec rather than about a name. The file is 51 bytes smaller than before the check existed.
  */
 export declare function checkDefinition(name: string, options: Record<string, OptionSpec>): void;
 /**
- * The whole door: the reserved names of V5, {@link checkDefinition}, and {@link checkEffects}.
+ * The whole door: {@link checkDefinition} — which carries V5's reserved names — and
+ * {@link checkEffects}.
  *
  * This exists as one function because it was two. `defineCommand` ran both; `Manifest.use()`
  * ran neither, so a plugin's command was admitted unread — and a plugin option named `json`

package/dist/definition.js

@@ -1,10 +1,13 @@
-import { kebab } from './names.js';
+import { camel, kebab } from './names.js';
 const TYPES = new Set(['string', 'boolean', 'number']);
 const EFFECTS = ['read_only', 'idempotent', 'non_idempotent'];
 export const WITHHELD = 'withheld';
 const DECLARED = [...EFFECTS, WITHHELD];
 const RESERVED = new Set(['json', 'help', 'schema', 'mcp', 'version', 'explain']);
-function checkRelationNames(name, key, spec, options) {
+function checkSpec(name, key, spec, options) {
+    if ((spec.minimum !== undefined || spec.maximum !== undefined || spec.integer !== undefined) && spec.type !== 'number') {
+        throw new Error(`burgee: option "${key}" of "${name}" declares a numeric bound but is not a number`);
+    }
     for (const field of ['dependsOn', 'exclusive']) {
         for (const other of spec[field] ?? []) {
             if (other !== key && other in options)
@@ -27,14 +30,13 @@ export function checkDefinition(name, options) {
             shorts.set(spec.short, key);
         }
         const flag = kebab(key);
-        const clash = flags.get(flag);
+        if (RESERVED.has(flag))
+            throw new Error(`burgee: option "${key}" is reserved and cannot be redefined`);
+        const clash = flags.get(flag) ?? (camel(flag) === key ? undefined : camel(flag));
         if (clash !== undefined)
             throw new Error(`burgee: options "${clash}" and "${key}" of "${name}" are both --${flag}`);
         flags.set(flag, key);
-        if ((spec.minimum !== undefined || spec.maximum !== undefined || spec.integer !== undefined) && spec.type !== 'number') {
-            throw new Error(`burgee: option "${key}" of "${name}" declares a numeric bound but is not a number`);
-        }
-        checkRelationNames(name, key, spec, options);
+        checkSpec(name, key, spec, options);
     }
 }
 function checkEffects(name, effects, runs) {
@@ -48,10 +50,6 @@ function checkEffects(name, effects, runs) {
     }
 }
 export function checkCommand(name, options, effects, runs) {
-    for (const key of Object.keys(options)) {
-        if (RESERVED.has(key) || RESERVED.has(kebab(key)))
-            throw new Error(`burgee: option "${key}" is reserved and cannot be redefined`);
-    }
     checkDefinition(name, options);
     checkEffects(name, effects, runs);
 }

package/dist/execute.js

@@ -360,6 +360,10 @@ function changedOf(node, data) {
     }
     return undefined;
 }
+function exitCodeOf(data) {
+    const code = isPlainObject(data) ? data['exitCode'] : undefined;
+    return isExitCode(code) ? code : ExitCode.OK;
+}
 function versionOf(manifest, io) {
     const declared = manifest.version ?? (typeof io.pkg?.data['version'] === 'string' ? io.pkg.data['version'] : undefined);
     if (declared === undefined)
@@ -420,7 +424,7 @@ async function emit(io, outcome) {
     const meta = { provenance: outcome.provenance ?? {}, ...(outcome.changed === undefined ? {} : { changed: outcome.changed }) };
     const envelope = { ok: true, data: outcome.data, meta };
     io.out.write(outcome.json ? `${JSON.stringify(envelope)}\n` : `${render(outcome.data)}\n`);
-    return await leave(io, ExitCode.OK);
+    return await leave(io, exitCodeOf(outcome.data));
 }
 async function report(cause, { manifest, io, argv, json, name }) {
     const failure = await describeFailure(cause, argv, resolveCommand(manifest, argv) ?? undefined);

package/dist/mcp.d.ts

@@ -2,9 +2,15 @@ import { type CommandNode, type Effects, type Manifest } from './manifest.js';
 import { type JsonSchema } from './schema.js';
 export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
 export interface ToolAnnotations {
-    readOnlyHint: boolean;
-    idempotentHint: boolean;
-    destructiveHint: boolean;
+    readOnlyHint?: boolean;
+    idempotentHint?: boolean;
+    destructiveHint?: boolean;
+    /**
+     * `'undeclared'`, and only ever that (G1). It appears on a command whose author said
+     * nothing — every commander and yargs command that did not call `.effects()` — and never
+     * beside a hint, because a hint is what a declaration produces.
+     */
+    effects?: 'undeclared';
 }
 export interface Tool {
     name: string;
@@ -18,20 +24,34 @@ export type Invoke = (argv: string[]) => Promise<{
     stderr: string;
     code: number;
 }>;
-/** MCP's hints, from the declared effects. `destructiveHint` is only ever false by declaration. */
-export declare function annotationsOf(effects: Effects): ToolAnnotations;
+/**
+ * MCP's hints, from the declared effects. `destructiveHint` is only ever false by declaration.
+ *
+ * No declaration returns no hints (G1). That is not a gap: MCP defines a default for each of
+ * the three — `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false` — so an
+ * absent hint already reads as *assume the worst*, in the client's own vocabulary and without
+ * burgee inventing a value it has no basis for. `effects: 'undeclared'` is the positive half:
+ * this command is not a `read_only` one, and it is not a `withheld` one either — nobody said.
+ */
+export declare function annotationsOf(effects?: Effects): ToolAnnotations;
 /** `config get` → `config_get`: MCP tool names are `[a-zA-Z0-9_-]`. */
 export declare const toolName: (node: CommandNode, root: string[]) => string;
 /**
- * The tool list: every runnable, visible command that declared what running it does.
+ * The tool list: every runnable, visible command an author has not withheld.
+ *
+ * One word is absent and one is not, and until 2026-09-21 they were the same thing. An
+ * author who wrote `'withheld'` thought about it and said no; that is what the word is for
+ * and it still means absent. An author who wrote nothing — which on burgee's own API
+ * `checkCommand` refuses, and which **every** command built through the commander or yargs
+ * façade is, because neither incumbent has a notion of effects and neither can be made to
+ * acquire one without breaking the suites that grade the façades — was treated the same way,
+ * so a migrated user's whole program was silently not a tool.
  *
- * Two commands are absent and for different reasons. One declared `'withheld'` — an author
- * who thought about it and said no, which is what that word is for. The other has no
- * `effects` at all, which `checkCommand` now refuses at declaration, so on burgee's own API
- * it cannot reach here; a command built through the commander or yargs façade still can,
- * because neither incumbent has a notion of effects and neither can be made to acquire one
- * without breaking the suites that grade the façades. The filter treats both as *not a
- * tool*, which is the same conservative reading it always had.
+ * Reading silence as refusal was conservative and it was also the thing standing between the
+ * product and its own pitch. Absent-from-the-list is strictly worse for the caller than
+ * present-with-honest-annotations: an agent that cannot see a command cannot decide about it,
+ * and cannot ask. So an undeclared command is listed and says so — see {@link annotationsOf}
+ * for why it carries no hints rather than a reassuring default.
  */
 export declare function toolsOf(manifest: Manifest): Tool[];
 /** A tool call's arguments back into argv: the command, its options, `--json`, then positionals in declared order. */

package/dist/mcp.js

@@ -6,6 +6,8 @@ const JSON_RPC_INVALID_REQUEST = -32600;
 const JSON_RPC_METHOD_NOT_FOUND = -32601;
 const JSON_RPC_INVALID_PARAMS = -32602;
 export function annotationsOf(effects) {
+    if (effects === undefined)
+        return { effects: 'undeclared' };
     return {
         readOnlyHint: effects === 'read_only',
         idempotentHint: effects !== 'non_idempotent',
@@ -21,7 +23,7 @@ function describe(node) {
 }
 export function toolsOf(manifest) {
     return runnable(manifest)
-        .filter((c) => c.effects !== undefined && c.effects !== WITHHELD)
+        .filter((c) => c.effects !== WITHHELD)
         .map((c) => ({ name: toolName(c, manifest.rootPath), description: describe(c), inputSchema: inputSchemaOf(c), annotations: annotationsOf(c.effects) }));
 }
 function optionArgs(node, args) {
@@ -59,8 +61,7 @@ async function callTool(session, params) {
     const given = params ?? {};
     const raw = given['name'];
     const name = typeof raw === 'string' ? raw : '';
-    const exposed = new Set(toolsOf(manifest).map((t) => t.name));
-    const node = exposed.has(name) ? runnable(manifest).find((c) => toolName(c, root) === name) : undefined;
+    const node = runnable(manifest).find((c) => c.effects !== WITHHELD && toolName(c, root) === name);
     if (node === undefined)
         return { error: { code: JSON_RPC_INVALID_PARAMS, message: `unknown tool "${name}"` } };
     const args = (given['arguments'] ?? {});

package/dist/migrate.d.ts

@@ -0,0 +1,142 @@
+import { type Graded } from './compat.js';
+/**
+ * A2 — the whole mapping, as data.
+ *
+ * Whole specifiers only. `burgee/commander` is not a key, which is what makes a second run
+ * over an already-migrated tree a no-op and lets the command declare `effects: 'idempotent'`.
+ */
+export declare const MAPPING: Readonly<Record<string, string>>;
+/** The packages a project depends on that this command is about (A1). */
+export declare const HOSTS: readonly ["commander", "yargs"];
+/** Why a file was left untouched. Both are named positions, never a guess (A4). */
+export type RefusalReason = 'deep-import' | 'non-literal-specifier';
+export interface Refusal {
+    /** Relative to the directory being migrated, with forward slashes on every platform. */
+    file: string;
+    line: number;
+    /** The specifier as written, or `''` for a dynamic specifier that is not a literal. */
+    specifier: string;
+    reason: RefusalReason;
+}
+/** One rewritten specifier, for the per-mapping rollup the report prints. */
+export interface Mapped {
+    from: string;
+    to: string;
+    imports: number;
+    files: number;
+}
+export interface Detection {
+    /** Hosts named in `package.json`'s dependencies — declared. */
+    declared: string[];
+    /** Hosts a source file actually imports — used. These two disagree more often than not. */
+    imported: string[];
+}
+export interface MigrationReport {
+    files: number;
+    imports: number;
+    mapped: Mapped[];
+    refused: Refusal[];
+    detected: Detection;
+    dependencies: {
+        before: string[];
+        removable: string[];
+        after: number;
+    };
+    graded: (Graded & {
+        host: string;
+    })[];
+    dryRun: boolean;
+    /** N7 — an idempotent command says whether it changed anything; silence is what an agent misreads. */
+    changed: boolean;
+    /** A8 — `RUNTIME` when anything was refused, so an agent branches on the code. */
+    exitCode: number;
+}
+interface Site {
+    specifier: string;
+    /** Offsets of the specifier's text, excluding the quotes. */
+    start: number;
+    end: number;
+    line: number;
+}
+interface Scan {
+    sites: Site[];
+    /** `import(x)` / `require(x)` where `x` is not a string literal — refused, never guessed. */
+    nonLiteral: number[];
+}
+/**
+ * One linear pass over the text: comments, strings, templates and regular expressions are
+ * skipped as the shapes they are, and every quoted literal is classified by the two code
+ * tokens in front of it.
+ *
+ * It is a scan, not a parse. What it cannot classify it refuses (A4); what it can, it knows
+ * exactly, because a module specifier is a string literal in one of five positions and
+ * nothing else in the grammar looks like that.
+ */
+export declare function scan(source: string): Scan;
+export interface Rewrite {
+    source: string;
+    mapped: {
+        from: string;
+        to: string;
+    }[];
+    refused: Omit<Refusal, 'file'>[];
+    /** Whether this file references a host at all. A file that does not is not "untouched", it is unrelated. */
+    relevant: boolean;
+}
+/**
+ * A file that names neither host anywhere cannot contain a specifier for one — and in a real
+ * repository that is almost every file.
+ *
+ * `includes` is a `memmem`; `scan` is a character loop. It is not what makes the command
+ * fast (the whole scan phase is 25 ms of a ~400 ms run over 1,000 files) — it is what keeps
+ * the work proportional to the files that could matter rather than to the repository, and
+ * on a `Buffer` it also skips decoding 3 MB of UTF-8 that nothing was going to read.
+ */
+export declare function mentionsAHost(source: string | Buffer): boolean;
+/**
+ * A2/A5 — map every host specifier in one file, or map none of them.
+ *
+ * The edits are applied from the end backwards so earlier offsets stay valid, and the
+ * source is returned unchanged the moment there is a refusal in it: the unit of success is
+ * the file, so the worst case is *nothing changed here, and here is why* (D-051).
+ */
+export declare function rewriteSource(source: string): Rewrite;
+/** Every source file under `dir`, relative and slash-separated so a report reads the same everywhere. */
+export declare function sourceFiles(dir: string, at?: string, found?: string[]): string[];
+/**
+ * `git status --porcelain`, or `undefined` where there is no repository to ask (A6).
+ *
+ * Through `bellpull` rather than `node:child_process`, because spawning is bellpull's job
+ * and `scripts/inline-implementation-lock.test.ts` says so — it caught the first draft of
+ * this file, which reached for `execFileSync` out of habit. burgee already depends on the
+ * package, and `migrate.js` is loaded lazily, so nothing that does not run `migrate` pays
+ * for the edge.
+ *
+ * Not a repository, no `git` on `PATH`, an unreadable directory: all the same answer, which
+ * is *there is nothing here that could be dirty*. A6 protects a reviewable diff, and where
+ * there is no repository there is no diff to protect — refusing instead would make the
+ * command unusable on a tarball for a safety that was never available.
+ */
+export declare function workingTree(dir: string): Promise<string[] | undefined>;
+/** A6 — a dirty tree has no reviewable diff to add to, so the command declines rather than writes. */
+export declare class DirtyTreeError extends Error {
+    readonly entries: string[];
+    readonly fix = "commit or stash your changes, or pass --force";
+    constructor(entries: string[]);
+}
+export interface MigrateOptions {
+    dir: string;
+    dryRun?: boolean;
+    force?: boolean;
+    /** Injected by the tests; the real `git status --porcelain` otherwise. */
+    status?: (dir: string) => string[] | undefined | Promise<string[] | undefined>;
+}
+/**
+ * Migrate one project: detect, rewrite, report (A1, A7, A8).
+ *
+ * Non-interactive by design (D-052). The second audience is an agent migrating a
+ * repository unattended, and a prompt is a wall; safety is `--dry-run` and the refusal on
+ * a dirty tree, not a question.
+ */
+export declare function migrate(options: MigrateOptions): Promise<MigrationReport>;
+export {};