burgee 0.10.0 → 0.11.1

package/README.md

@@ -15,7 +15,7 @@
   <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/v/burgee?style=flat-square&color=0a6b47" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/dm/burgee?style=flat-square" alt="npm downloads" /></a>
   <img src="https://img.shields.io/badge/dependencies-5%20in--family-0a6b47?style=flat-square" alt="Five dependencies, all in this repository: bellpull, closeout, linegauge, roundel, seniority" />
-  <img src="https://img.shields.io/badge/Node.js-24+-green.svg?style=flat-square" alt="Node.js 24+" />
+  <img src="https://img.shields.io/badge/Node.js-20.19%2B%20%7C%2022.13%2B-green.svg?style=flat-square" alt="Node.js 20.19+ or 22.13+" />
   <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
 </p>
 
@@ -46,6 +46,7 @@ run(defineCommand({
   name: 'greet',
   description: 'Greet someone by name',
   options: { name: { type: 'string', required: true, description: 'who to greet' } },
+  effects: 'read_only', // what running it does to the world; required, and what --mcp reads
   run: ({ options }) => ({ greeting: `hello, ${options.name}` }),
 }));
 ```
@@ -55,7 +56,7 @@ $ node cli.mjs --name ada
 greeting: hello, ada
 
 $ node cli.mjs --json --name ada
-{"ok":true,"data":{"greeting":"hello, ada"}}
+{"ok":true,"data":{"greeting":"hello, ada"},"meta":{"provenance":{"name":{"source":"flag","location":"--name"}}}}
 
 $ node cli.mjs            # exit 2
 error: missing required option --name
@@ -154,9 +155,11 @@ the declaration read by a different reader.
 
 ### How do I expose a CLI over MCP?
 
-Run it with `--mcp`: the same manifest is served as MCP tools over stdio. A command becomes
-a tool only when it declares its `effects` (`read_only`, `idempotent` or `non_idempotent`),
-so nothing reaches an agent by accident. Register it with any stdio client:
+Run it with `--mcp`: the same manifest is served as MCP tools over stdio. Every runnable
+command declares its `effects` — `read_only`, `idempotent` or `non_idempotent`, which become
+MCP's hints, or `withheld`, which keeps it out of the tool list — so nothing reaches an
+agent by accident. On `burgee/commander` and `burgee/yargs`, a command that declared
+nothing is still listed, marked `effects: 'undeclared'`. Register it with any stdio client:
 
 ```json
 { "mcpServers": { "mytool": { "command": "npx", "args": ["mytool", "--mcp"] } } }
@@ -164,7 +167,7 @@ so nothing reaches an agent by accident. Register it with any stdio client:
 
 ### Does it have dependencies?
 
-None outside this repository. `burgee` installs five packages from its own family —
+None outside the burgee family. `burgee` installs five packages from that family —
 `bellpull`, `closeout`, `linegauge`, `roundel` and `seniority` — and each of those takes
 nothing from outside it either: one repository, one release pipeline, one supply chain to
 audit.

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 export declare const brandCommand: import("./execute.js").Command<{
     readonly lead: {
         readonly type: "string";

package/dist/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DEFAULT_GROUND, defineBurgee, opposedField } from './brand.js';

package/dist/commander/command.d.ts

@@ -58,6 +58,22 @@ export interface OutputContext {
     error?: boolean;
 }
 export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
+/**
+ * commander's option-value types, as `typings/index.d.ts` declares them. `any` is
+ * commander's choice and the point: `program.opts().port` is usable without a cast, and
+ * `opts<T>()` narrows it — a program written against commander's types relies on both;
+ * `unknown` here breaks every `opts().x` such a program reads.
+ */
+export type OptionValues = Record<string, any>;
+/** Where an option's value came from. A string, so an author can define their own; the known ones autocomplete. */
+export type OptionValueSource = 'default' | 'config' | 'env' | 'cli' | 'implied' | (string & Record<never, never>) | undefined;
+/** What `.configureHelp()` takes: any subset of `Help`'s methods and settings. */
+export type HelpConfiguration = Partial<Help>;
+/** `.parseOptions()`'s split of an argv into operands and unknown options. */
+export interface ParseOptionsResult {
+    operands: string[];
+    unknown: string[];
+}
 export type HookListener = (thisCommand: Command, actionCommand: Command) => void | Promise<void>;
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
 export type AddHelpTextContext = {
@@ -236,14 +252,11 @@ export declare class Command extends EventEmitter {
      *     sub --unknown uuu op => [sub], [--unknown uuu op]
      *     sub -- --unknown uuu op => [sub --unknown uuu op], []
      */
-    parseOptions(args: string[]): {
-        operands: string[];
-        unknown: string[];
-    };
-    /** Local option values as key-value pairs. */
-    opts(): Record<string, unknown>;
+    parseOptions(args: string[]): ParseOptionsResult;
+    /** Local option values as key-value pairs; `opts<T>()` types them, as commander's own declaration does. */
+    opts<T extends OptionValues = OptionValues>(): T;
     /** Merged local and global option values; globals overwrite locals. */
-    optsWithGlobals(): Record<string, unknown>;
+    optsWithGlobals<T extends OptionValues = OptionValues>(): T;
     /** Display an error message and exit (or call exitOverride). */
     error(message: string, errorOptions?: ErrorOptions): never;
     /** One failure as the envelope (E3, G5); `fix` only when one candidate was named. */
@@ -316,7 +329,17 @@ export declare class Command extends EventEmitter {
      */
     get manifest(): Manifest;
     _project(manifest: Manifest): void;
-    /** Options as the manifest describes them, on a null-prototype record. */
+    /**
+     * Options as the manifest describes them, on a null-prototype record — keyed so that the
+     * spelling every surface derives from a key, `--${kebab(key)}`, is a flag commander accepts.
+     *
+     * Commander negates only what it was told to, where burgee's own parser negates every
+     * boolean. So a boolean is `negatable` here only when the program declared its `--no-` twin,
+     * which folds onto it rather than appearing twice; and a `--no-x` declared alone, which has
+     * no `--x`, is described as the switch it is, under `noX`. Before this, `--no-color` was
+     * published as `color` with `flag: '--color'`: completions offered `--color` and
+     * `--no-skip-blank`, and `--mcp` sent `--color` — each refused by the parser behind them.
+     */
     _optionSpecs(): Record<string, OptionSpec>;
     /** burgee: declare what the command does to the world (N6). This is what exposes it as an MCP tool (N2). */
     effects(value: DeclaredEffects): this;

package/dist/commander/command.js

@@ -5,6 +5,7 @@ import { stripVTControlCharacters } from 'node:util';
 import * as crossSpawn from 'bellpull/cross-spawn';
 import { ExitCode } from '../exit-code.js';
 import { Manifest } from '../manifest.js';
+import { camel } from '../names.js';
 import { host } from '../runtime.js';
 import { machineJson, schemaOf } from '../schema.js';
 import { suggestSimilar } from '../suggest.js';
@@ -1413,6 +1414,10 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
     _optionSpecs() {
         const specs = Object.create(null);
         for (const option of this.options) {
+            const name = option.attributeName();
+            const paired = this.options.some((o) => o.negate !== option.negate && o.attributeName() === name);
+            if (option.negate && paired)
+                continue;
             const spec = { type: option.required || option.optional ? 'string' : 'boolean' };
             if (option.description)
                 spec.description = option.description;
@@ -1424,7 +1429,9 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 spec.default = option.defaultValue;
             if (option.envVar)
                 spec.env = option.envVar;
-            Object.defineProperty(specs, option.attributeName(), { value: spec, enumerable: true, writable: true, configurable: true });
+            if (spec.type === 'boolean')
+                spec.negatable = paired;
+            Object.defineProperty(specs, option.negate ? camel(option.name()) : name, { value: spec, enumerable: true, writable: true, configurable: true });
         }
         return specs;
     }

package/dist/commander.d.ts

@@ -4,13 +4,19 @@
  * `.sdlc/intents/commander-compat/spec.md` and `npm run compat`.
  */
 import { Argument } from './commander/argument.js';
-import { Command } from './commander/command.js';
+import { Command, type OutputConfiguration as ResolvedOutputConfiguration } from './commander/command.js';
 import { Option } from './commander/option.js';
 export { Argument, humanReadableArgName } from './commander/argument.js';
-export { Command, useColor, type AddHelpTextContext, type AddHelpTextPosition, type BurgeeParseOptions, type CommandOptions, type ErrorOptions, type ExecutableCommandOptions, type HookEvent, type HookListener, type OutputConfiguration, type OutputContext, type ParseOptions, } from './commander/command.js';
+export { Command, useColor, type AddHelpTextContext, type AddHelpTextPosition, type BurgeeParseOptions, type CommandOptions, type ErrorOptions, type ExecutableCommandOptions, type HelpConfiguration, type HookEvent, type HookListener, type OptionValueSource, type OptionValues, type OutputContext, type ParseOptions, type ParseOptionsResult, } from './commander/command.js';
 export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander/error.js';
 export { Help, type HelpContext } from './commander/help.js';
 export { DualOptions, Option } from './commander/option.js';
+/**
+ * commander's `OutputConfiguration`: every member optional, because `.configureOutput()`
+ * takes any subset of them and a typed program annotates exactly that subset. What
+ * `.configureOutput()` hands back is the resolved, complete one.
+ */
+export type OutputConfiguration = Partial<ResolvedOutputConfiguration>;
 /** The root command, for programs that never construct their own. */
 export declare const program: Command;
 export declare const createCommand: (name?: string) => Command;

package/dist/completions.js

@@ -16,7 +16,7 @@ function children(manifest, at) {
 function nodeOf(manifest, c) {
     const visible = Object.fromEntries(Object.entries(c.options)
         .filter(([, spec]) => spec.hidden !== true)
-        .map(([name, spec]) => [name, spec.type === 'boolean' ? { ...spec, negatable: true } : spec]));
+        .map(([name, spec]) => [name, { ...spec, negatable: spec.type === 'boolean' && spec.negatable !== false }]));
     const isRoot = c.path.length === manifest.rootPath.length;
     return {
         path: c.path.slice(manifest.rootPath.length),

package/dist/execute.js

@@ -127,7 +127,7 @@ function toParseConfig(specs, withConfig) {
             ...(spec.short === undefined ? {} : { short: spec.short }),
             ...(spec.multiple === true ? { multiple: true } : {}),
         };
-        if (spec.type === 'boolean')
+        if (spec.type === 'boolean' && spec.negatable !== false)
             config[`${NO}${kebab(name)}`] = { type: 'boolean' };
     }
     return config;
@@ -238,7 +238,7 @@ async function describeFailure(cause, argv, node) {
         const dash = explain.singleDashHint(argv);
         if (dash !== undefined)
             return { code: ExitCode.USAGE, message, hint: dash };
-        const better = explain.unknownOption(cause, Object.keys(node?.options ?? {}));
+        const better = explain.unknownOption(cause, Object.keys(node?.options ?? {}).map(kebab));
         return { code: ExitCode.USAGE, message, hint: 'run --help to see the available options', ...better };
     }
     return { code: ExitCode.RUNTIME, message };
@@ -505,7 +505,7 @@ export async function run(target, opts = {}) {
     manifest.rootPath = [target.name];
     manifest.add({
         path: [target.name],
-        ...(target.description === undefined ? {} : { description: target.description }),
+        ...helpFields(target),
         options: target.options ?? {},
         ...(target.run === undefined ? {} : { run: target.run }),
     });

package/dist/manifest.d.ts

@@ -78,6 +78,13 @@ export interface OptionSpec {
     /** `true` renders `(deprecated)`; a string names the replacement: `(deprecated: use --force)` (yargs #2248). */
     deprecated?: boolean | string;
     hidden?: boolean;
+    /**
+     * `boolean` only: whether `--no-<name>` is accepted. Every boolean is negatable unless this
+     * says `false`. burgee's own parser negates every boolean (see `toParseConfig`); the
+     * commander façade sets `false` where commander would refuse the negation, so completions
+     * and `--mcp` never offer or send a flag the parser behind them rejects.
+     */
+    negatable?: boolean;
     /** The shared set this option was copied from (M4); `--schema` carries it, help lists the option like any other. */
     sharedFrom?: string;
 }

package/dist/mcp.d.ts

@@ -34,7 +34,11 @@ export type Invoke = (argv: string[]) => Promise<{
  * 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_-]`. */
+/**
+ * `config get` → `config_get`: MCP tool names are `[a-zA-Z0-9_-]`, one character or more. A
+ * program whose root runs — a single `run(defineCommand(…))`, a commander program with a root
+ * `.action()` — has no typed name at all, so its tool is named after the program.
+ */
 export declare const toolName: (node: CommandNode, root: string[]) => string;
 /**
  * The tool list: every runnable, visible command an author has not withheld.

package/dist/mcp.js

@@ -1,5 +1,6 @@
 import { createInterface } from 'node:readline';
 import { WITHHELD } from './definition.js';
+import { kebab } from './names.js';
 import { inputSchemaOf, runnable, typedName } from './schema.js';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
 const JSON_RPC_INVALID_REQUEST = -32600;
@@ -14,7 +15,7 @@ export function annotationsOf(effects) {
         destructiveHint: effects === 'non_idempotent',
     };
 }
-export const toolName = (node, root) => typedName(node, root).replaceAll(' ', '_');
+export const toolName = (node, root) => (typedName(node, root) || root.join(' ')).replaceAll(' ', '_');
 function describe(node) {
     const parts = [node.description ?? node.summary ?? ''];
     for (const e of node.examples ?? [])
@@ -32,12 +33,13 @@ function optionArgs(node, args) {
         const value = args[name];
         if (value === undefined || value === null)
             continue;
-        if (spec.type === 'boolean') {
-            if (value === true)
-                out.push(`--${name}`);
-        }
-        else
-            out.push(`--${name}`, String(value));
+        const flag = `--${kebab(name)}`;
+        if (spec.type !== 'boolean')
+            out.push(flag, String(value));
+        else if (value === true)
+            out.push(flag);
+        else if (value === false && spec.negatable !== false && (spec.default === true || spec.env !== undefined))
+            out.push(`--no-${kebab(name)}`);
     }
     return out;
 }

package/dist/migrate.d.ts

@@ -8,8 +8,24 @@ import { type Graded } from './compat.js';
 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';
+/**
+ * Every name each target exports — values and types alike — so a rewrite that moves
+ * `import { Argv } from 'yargs'` can first ask whether `burgee/yargs` has an `Argv`.
+ *
+ * A specifier-only rewrite (D-050) cannot tell a value from a type, and does not need to:
+ * a name the target does not export breaks the build either way. This is data rather than
+ * a lookup because the lookup is the TypeScript checker, which is the dependency this
+ * command exists not to have; `facade-types.test.ts` holds the table equal to what the
+ * checker sees in `dist/*.d.ts`, so it cannot drift from the façades it describes.
+ */
+export declare const FACADE_EXPORTS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Why a file was left untouched. Each is a named position, never a guess (A4).
+ *
+ * `unknown-export` is a named import the target does not export — rewriting it would turn a
+ * working import into TS2305 or a `SyntaxError` at load, so the file stays as it was.
+ */
+export type RefusalReason = 'deep-import' | 'non-literal-specifier' | 'unknown-export';
 export interface Refusal {
     /** Relative to the directory being migrated, with forward slashes on every platform. */
     file: string;
@@ -17,6 +33,23 @@ export interface Refusal {
     /** The specifier as written, or `''` for a dynamic specifier that is not a literal. */
     specifier: string;
     reason: RefusalReason;
+    /** For `unknown-export`: the names the target does not export. */
+    names?: string[];
+}
+/**
+ * A type-only import left on the incumbent because the façade does not export every name in
+ * it. Types are erased, so the file's values still move to burgee and the program runs on it;
+ * the types keep compiling against the incumbent's declarations, which is why the incumbent
+ * is then not reported removable.
+ */
+export interface Kept {
+    file: string;
+    line: number;
+    specifier: string;
+    /** The names the façade does not export. */
+    names: string[];
+    /** The note a reader acts on. */
+    note: string;
 }
 /** One rewritten specifier, for the per-mapping rollup the report prints. */
 export interface Mapped {
@@ -36,6 +69,8 @@ export interface MigrationReport {
     imports: number;
     mapped: Mapped[];
     refused: Refusal[];
+    /** Type-only imports left pointing at the incumbent, each with the note that says why. */
+    kept: Kept[];
     detected: Detection;
     dependencies: {
         before: string[];
@@ -57,6 +92,11 @@ interface Site {
     start: number;
     end: number;
     line: number;
+    /**
+     * For `import … from` and `export … from`: the code tokens between the keyword and `from`
+     * — the import clause, which is all `bindingsOf` needs. Absent for the other three positions.
+     */
+    clause?: string[];
 }
 interface Scan {
     sites: Site[];
@@ -80,6 +120,7 @@ export interface Rewrite {
         to: string;
     }[];
     refused: Omit<Refusal, 'file'>[];
+    kept: Omit<Kept, 'file'>[];
     /** Whether this file references a host at all. A file that does not is not "untouched", it is unrelated. */
     relevant: boolean;
 }
@@ -93,6 +134,19 @@ export interface Rewrite {
  * 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;
+/**
+ * The names an import or re-export clause asks the module for, and whether the whole
+ * statement is type-only (`import type …`, `export type …`).
+ *
+ * Read off the tokens the scan already has: `{ a, type b, c as d }` asks for `a`, `b` and
+ * `c`; a default or namespace binding asks for no name a façade could lack (`default` is
+ * the factory, and `* as ns` is checked where it is used, which a scan cannot see). A name
+ * written as a string (`{ 'a-b' as c }`) is left unverified rather than guessed at.
+ */
+export declare function bindingsOf(clause: readonly string[]): {
+    typeOnly: boolean;
+    names: string[];
+};
 /**
  * A2/A5 — map every host specifier in one file, or map none of them.
  *

package/dist/migrate.js

@@ -11,6 +11,89 @@ export const MAPPING = {
     'yargs/helpers': 'burgee/yargs/helpers',
 };
 export const HOSTS = ['commander', 'yargs'];
+export const FACADE_EXPORTS = {
+    'burgee/commander': [
+        'AddHelpTextContext',
+        'AddHelpTextPosition',
+        'Argument',
+        'BurgeeParseOptions',
+        'Command',
+        'CommandOptions',
+        'CommanderError',
+        'DualOptions',
+        'ErrorOptions',
+        'ExecutableCommandOptions',
+        'Help',
+        'HelpConfiguration',
+        'HelpContext',
+        'HookEvent',
+        'HookListener',
+        'InvalidArgumentError',
+        'InvalidOptionArgumentError',
+        'Option',
+        'OptionValueSource',
+        'OptionValues',
+        'OutputConfiguration',
+        'OutputContext',
+        'ParseOptions',
+        'ParseOptionsResult',
+        'createArgument',
+        'createCommand',
+        'createOption',
+        'humanReadableArgName',
+        'program',
+        'useColor',
+    ],
+    'burgee/yargs': [
+        'Arguments',
+        'ArgumentsCamelCase',
+        'Argv',
+        'AsyncCompletionFunction',
+        'BuilderArguments',
+        'BuilderCallback',
+        'Choices',
+        'CommandBuilder',
+        'CommandModule',
+        'CompletionCallback',
+        'Defined',
+        'DetailedArguments',
+        'FallbackCompletionFunction',
+        'InferredOptionType',
+        'InferredOptionTypeInner',
+        'InferredOptionTypePrimitive',
+        'InferredOptionTypes',
+        'MiddlewareFunction',
+        'Options',
+        'ParseCallback',
+        'ParsedCommand',
+        'Parser',
+        'ParserConfigurationOptions',
+        'PlatformShim',
+        'PositionalOptions',
+        'PositionalOptionsType',
+        'PromiseCompletionFunction',
+        'RequireDirectoryOptions',
+        'SyncCompletionFunction',
+        'ToArray',
+        'ToNumber',
+        'ToString',
+        'YError',
+        'YargsInstance',
+        'applyExtends',
+        'argsert',
+        'camelCase',
+        'decamelize',
+        'default',
+        'hideBin',
+        'isPromise',
+        'isYargsInstance',
+        'looksLikeNumber',
+        'objFilter',
+        'parseCommand',
+        'platformShim',
+    ],
+    'burgee/yargs/helpers': ['Parser', 'applyExtends', 'hideBin'],
+};
 const WORD = /[A-Za-z0-9_$]/;
 const DIVIDES = new Set([')', ']', '}']);
 function startsRegex(previous) {
@@ -123,12 +206,25 @@ function push(tokens, text, line) {
     if (tokens.pending && text !== QUOTED && text !== ')')
         tokens.nonLiteral.push(line);
     tokens.pending = text === '(' && (tokens.previous === 'import' || tokens.previous === 'require');
+    if (text === 'import' || text === 'export')
+        tokens.clause = [];
+    else if (text === '(' || text === '=' || tokens.previous === 'from')
+        tokens.clause = undefined;
+    else
+        tokens.clause?.push(text);
     tokens.before = tokens.previous;
     tokens.previous = text;
 }
+function siteOf(source, at, tokens) {
+    const { open, close, line } = at;
+    const site = { specifier: source.slice(open + 1, close - 1), start: open + 1, end: close - 1, line };
+    if (tokens.previous === 'from' && tokens.clause !== undefined)
+        site.clause = tokens.clause.slice(0, -1);
+    return site;
+}
 export function scan(source) {
     const sites = [];
-    const tokens = { previous: '', before: '', pending: false, nonLiteral: [] };
+    const tokens = { previous: '', before: '', pending: false, nonLiteral: [], clause: undefined };
     let line = 1;
     let i = 0;
     while (i < source.length) {
@@ -143,7 +239,7 @@ export function scan(source) {
             const c = source.charAt(i);
             const quoted = c === "'" || c === '"';
             if (quoted && isSpecifier(tokens.previous, tokens.before))
-                sites.push({ specifier: source.slice(i + 1, literal - 1), start: i + 1, end: literal - 1, line });
+                sites.push(siteOf(source, { open: i, close: literal, line }, tokens));
             push(tokens, quoted ? QUOTED : 'lit', line);
             line += newlines(source, i, literal);
             i = literal;
@@ -169,27 +265,71 @@ function isDeep(specifier) {
         return false;
     return HOSTS.some((host) => specifier.startsWith(`${host}/`));
 }
+export function bindingsOf(clause) {
+    const typeOnly = clause[0] === 'type' && clause.length > 1;
+    const open = clause.indexOf('{');
+    const close = clause.indexOf('}', open);
+    if (open === -1 || close === -1)
+        return { typeOnly, names: [] };
+    const names = [];
+    let element = [];
+    for (const token of [...clause.slice(open + 1, close), ',']) {
+        if (token !== ',') {
+            element.push(token);
+            continue;
+        }
+        const modifier = element[0] === 'type' && element.length > 1 && element[1] !== 'as';
+        const name = modifier ? element[1] : element[0];
+        if (name !== undefined && name !== 'default' && name !== QUOTED && WORD.test(name.charAt(0)))
+            names.push(name);
+        element = [];
+    }
+    return { typeOnly, names };
+}
+function missingFrom(site, to) {
+    const exported = FACADE_EXPORTS[to];
+    if (site.clause === undefined || exported === undefined)
+        return { typeOnly: false, missing: [] };
+    const { typeOnly, names } = bindingsOf(site.clause);
+    return { typeOnly, missing: names.filter((name) => !exported.includes(name)) };
+}
 export function rewriteSource(source) {
     if (!mentionsAHost(source))
-        return { source, mapped: [], refused: [], relevant: false };
+        return { source, mapped: [], refused: [], kept: [], relevant: false };
     const { sites, nonLiteral } = scan(source);
     const hits = sites.filter((s) => MAPPING[s.specifier] !== undefined || isDeep(s.specifier));
     if (hits.length === 0)
-        return { source, mapped: [], refused: [], relevant: false };
+        return { source, mapped: [], refused: [], kept: [], relevant: false };
+    const kept = [];
+    const unknown = [];
+    const moving = [];
+    for (const site of hits) {
+        const to = MAPPING[site.specifier];
+        if (to === undefined)
+            continue;
+        const { typeOnly, missing } = missingFrom(site, to);
+        if (missing.length === 0)
+            moving.push(site);
+        else if (typeOnly)
+            kept.push({ line: site.line, specifier: site.specifier, names: missing, note: `${to} does not export ${missing.join(', ')}; this type-only import stays on '${site.specifier}', so keep its types installed` });
+        else
+            unknown.push({ line: site.line, specifier: site.specifier, reason: 'unknown-export', names: missing });
+    }
     const refused = [
         ...hits.filter((s) => isDeep(s.specifier)).map((s) => ({ line: s.line, specifier: s.specifier, reason: 'deep-import' })),
         ...nonLiteral.map((line) => ({ line, specifier: '', reason: 'non-literal-specifier' })),
+        ...unknown,
     ].sort((a, b) => a.line - b.line);
     if (refused.length > 0)
-        return { source, mapped: [], refused, relevant: true };
+        return { source, mapped: [], refused, kept: [], relevant: true };
     let out = source;
     const mapped = [];
-    for (const site of [...hits].sort((a, b) => b.start - a.start)) {
+    for (const site of moving.sort((a, b) => b.start - a.start)) {
         const to = MAPPING[site.specifier];
         out = `${out.slice(0, site.start)}${to}${out.slice(site.end)}`;
         mapped.push({ from: site.specifier, to });
     }
-    return { source: out, mapped: mapped.reverse(), refused: [], relevant: true };
+    return { source: out, mapped: mapped.reverse(), refused: [], kept, relevant: true };
 }
 const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts']);
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.turbo', '.next', '.output', '.cache', '.vercel']);
@@ -230,7 +370,7 @@ export class DirtyTreeError extends Error {
         this.name = 'DirtyTreeError';
     }
 }
-const EMPTY = { source: '', mapped: [], refused: [], relevant: false };
+const EMPTY = { source: '', mapped: [], refused: [], kept: [], relevant: false };
 async function migrateBatch(dir, batch, write) {
     const sources = await Promise.all(batch.map(async (file) => await readFile(join(dir, file))));
     const results = sources.map((bytes) => (mentionsAHost(bytes) ? rewriteSource(bytes.toString('utf8')) : EMPTY));
@@ -264,9 +404,10 @@ export async function migrate(options) {
     }
     const all = results.flatMap(({ file, result }) => result.mapped.map((m) => ({ ...m, file })));
     const refused = results.flatMap(({ file, result }) => result.refused.map((r) => ({ file, ...r })));
-    const imported = [...new Set(results.flatMap(({ result }) => (result.relevant ? result.mapped.map((m) => m.from) : [])))];
+    const kept = results.flatMap(({ file, result }) => result.kept.map((k) => ({ file, ...k })));
+    const imported = [...new Set(results.flatMap(({ result }) => (result.relevant ? [...result.mapped.map((m) => m.from), ...result.kept.map((k) => k.specifier)] : [])))];
     const declared = await declaredHosts(dir);
-    const stillUsed = new Set(refused.map((r) => r.specifier.split('/')[0] ?? ''));
+    const stillUsed = new Set([...refused, ...kept].map((r) => r.specifier.split('/')[0] ?? ''));
     const removable = declared.filter((host) => !stillUsed.has(host));
     const touched = [...new Set(all.map((m) => m.file))];
     return {
@@ -274,6 +415,7 @@ export async function migrate(options) {
         imports: all.length,
         mapped: rollup(all),
         refused,
+        kept,
         detected: { declared, imported: [...new Set(imported.map((s) => s.split('/')[0] ?? s))].sort() },
         dependencies: { before: declared, removable, after: declared.length - removable.length },
         graded: gradedFor([...new Set([...declared, ...imported.map((s) => s.split('/')[0] ?? s)])].sort()),