@automaton-labs/aib 0.0.7 → 0.0.9

package/dist/help/topics/first-setup.md

@@ -81,11 +81,12 @@ Example:
 
 5. Configure import rules
 
-importRules control imports created or expanded by move/modulePlan mutation cleanup.
-They do not rewrite the whole project.
-
-AIB starts from IDE/TS import preferences.
-For mutation cleanup, matching importRules in aib.json take priority.
+importRules control imports created or expanded by move/modulePlan mutation cleanup.
+They do not rewrite the whole project.
+
+A non-empty importRules block in aib.json is the complete AIB import-style authority.
+Omitted fields keep TypeScript/AIB defaults; they are not filled from editor settings.
+When importRules is empty, AIB may reuse explicit workspace-local IDE/TS preferences.
 Do not assume IDE/TS defaults match the repo style.
 
 Fields:

package/dist/help/topics/help-protocol.md

@@ -1,5 +1,5 @@
 After context compaction, always run:
-aib help help-protocol quick-map
+aib help help-protocol quick-map recipes rules
 aib config aliases
 
 Use focused help when you would otherwise guess how a known AIB capability works.
@@ -14,11 +14,12 @@ aib help config-setup.import-normalize imports.normalize
 
 Refresh focused config help by signal:
 - repeated long paths: aib help config-setup.aliases
-- wrong move/modulePlan imports: aib help config-setup.import-rules
+- imports created by mutation do not match repo style: aib help config-setup.import-rules
 - noisy tree/graph output: aib help config-setup.excludes
 - too many visible tsconfigs: aib help config-setup.tsconfigs
 
 When refreshing multiple areas, request them together instead of one by one.
+Include broad shared topics only once.
 
 Example:
-aib help patterns mutation inspect inspect.file inspect.code imports.normalize
+aib help mutation moveToDir renameFile inspect inspect.file inspect.deps

package/dist/help/topics/import.base.md

@@ -0,0 +1,36 @@
+Import mutations change import declarations and import/export specifiers.
+
+Use them when the import target or import style is the intent.
+
+Current import mutation intents:
+- imports.normalize changes import style for already-correct targets.
+- imports.useBarrel moves eligible consumers to a barrel/index boundary.
+- imports.useDirect moves eligible consumers from a barrel back to direct source imports.
+
+Do not use imports.normalize when the real intent is to force a specific barrel boundary.
+Do not use imports.useBarrel/useDirect when the real intent is only alias-vs-relative style cleanup.
+
+Shared controls:
+
+@scope       consumer file or directory scope to scan
+@files       explicit consumer files to scan
+pathExclude  files, directories, or glob-like patterns to skip
+symbols      exported names to update, when supported by the operation
+
+Prefer @scope for a bounded area.
+Use @files for a small known consumer set.
+Use pathExclude for tests, generated files, fixtures, or migration-excluded areas.
+
+Use symbols only when the request should affect part of the import surface.
+Do not add symbols by default.
+
+Choose the import operation by intent:
+
+Use imports.normalize after imports already point to the right files/modules, but their specifier style should change.
+
+Use imports.useBarrel when an existing barrel/index file should become the import boundary.
+
+Use imports.useDirect when a barrel boundary should be removed for selected consumers.
+
+If both target boundary and style are wrong, change the boundary first.
+Normalize style only after the boundary is correct.

package/dist/help/topics/import.rebase.md

@@ -0,0 +1,83 @@
+Import Boundary Mutations
+
+Import boundary mutations change where consumers import exported symbols from.
+
+Use imports.useBarrel when an existing barrel file should become the import boundary.
+Use imports.useDirect when consumers currently import through a barrel but should import directly from source files.
+
+Both operations scan a consumer scope and rewrite eligible ES named imports.
+
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
+
+If a name is ambiguous, use selectors.
+
+Syntax:
+
+@scope <consumer-scope>
+imports.useBarrel <barrel-file> [pathExclude=[...]] [symbols=[...]]
+
+@scope <consumer-scope>
+imports.useDirect <barrel-file> [pathExclude=[...]] [symbols=[...]]
+
+Controls:
+
+@scope       consumer file or directory scope to scan
+pathExclude  consumer files, directories, or glob-like patterns to leave unchanged
+symbols      exported barrel names to update
+
+Use pathExclude for tests, generated files, fixtures, or migration-excluded areas.
+
+By default, do not list symbols.
+AIB reads the barrel and rewrites eligible imports for exported names it can resolve.
+Use symbols only when the request must affect a specific subset of the barrel surface.
+
+Run:
+aib mutate execute --stdin
+
+Use a barrel as the import boundary:
+
+Input:
+@scope src/features
+imports.useBarrel src/logs/index.ts
+
+Use direct source imports instead of a barrel:
+
+Input:
+@scope src/features
+imports.useDirect src/logs/index.ts
+
+Skip consumers that should not be rewritten:
+
+Input:
+@scope src/features
+imports.useBarrel src/logs/index.ts pathExclude=["**/*.test.ts","src/generated/**"]
+
+Limit the request to selected exported names:
+
+Input:
+@scope src/features
+imports.useDirect src/logs/index.ts symbols=[parseLogsQuery,LogsQuery]
+
+Compatibility
+
+Supported:
+- ES named imports
+- named re-exports
+- star re-exports
+- type-only named imports
+- aliased named re-exports
+
+Skipped or unsupported:
+- CommonJS require/module.exports
+- default re-exports
+- namespace imports
+- side-effect imports
+- default import parts
+
+Skipped imports are not rewritten.

package/dist/help/topics/inspect.aliasCandidates.md

@@ -0,0 +1,37 @@
+Find repeated TypeScript import prefixes that may be worth turning into TS path aliases.
+
+Use aliasCandidates when imports share long prefixes and you want evidence for adopting an existing alias or creating a new one.
+
+The advisor collects lexical import evidence, then validates shortlisted candidates against repo topology and TypeScript resolution for every owning tsconfig. Incomplete coverage, incompatible mappings, package-boundary violations, and other hard conflicts are rejected rather than rescued by ranking.
+
+Output separates evidence filters from the provisional ranking policy. Token savings use a deterministic path estimate and are not a Codex billing estimate. Parent and child candidates are compared by marginal coverage so overlapping imports are not counted twice.
+
+Candidates are classified as recommended, review, optional, or rejected. Creating a new alias remains review-only when runtime support or token confidence is not proven.
+
+This command is a read-only advisor. It does not edit tsconfig or rewrite imports.
+
+Run:
+aib inspect aliasCandidates <scope>
+
+DSL:
+aliasCandidates scope=src/main limit=20
+
+Options:
+limit       max candidates to print
+minImports  lexical evidence prefilter; not the ranking threshold
+minFiles    importing-file evidence prefilter; not the ranking threshold
+candidate   filter by source prefix or alias pattern
+detail      sum or examples
+
+Find candidates:
+
+Run:
+aib inspect aliasCandidates src/main
+
+Show examples for one suggested alias:
+
+Run:
+aib inspect aliasCandidates src/main --candidate "#services/*" --detail examples
+
+DSL:
+aliasCandidates scope=src/main candidate="#services/*" detail=examples

package/dist/help/topics/inspect.code.md

@@ -1,10 +1,4 @@
-Use code to fetch exact declarations or members.
-It returns focused code without reading the whole file.
-
-Good for:
-- reading a known function, class, method, declaration, `default`, or `IIFE#N`
-- fetching several related code blocks in one request
-- keeping context focused on code needed for the current task
+Use code when you know file path and declaration/member selector, but do not know ranges.
 
 Controls:
 file, entity, entities, parent, show, ranges

package/dist/help/topics/inspect.file.md

@@ -2,30 +2,21 @@ Use file to map top-level declarations physically present in one file.
 Exported declarations are marked in the output.
 It shows what lives in the file before you decide whether to read code.
 
-Good for:
-- mapping a file
-- listing top-level declarations
-- seeing default exports, decorators, IIFEs, and runtime calls
+Good for:
+- mapping a file
+- listing top-level declarations
+- seeing default exports, decorators, IIFEs, and runtime calls
 - checking whether a file contains real declarations or mostly re-exports
 
-Do not add limit just in case.
-file output is compact and most files have far fewer than 100 top-level declarations.
-Use limit only after file output is actually too large.
-
-Controls:
-file, ranges, localOnly
-
-Specific:
-localOnly   show local declarations and reexports without resolving facade API; +localOnly
-
-Defaults: +ranges
+Controls:
+file, ranges
+
+Defaults: +ranges
 Use -ranges to show names without ranges.
 
 Run:
 aib inspect --stdin
 
-Input:
-file @svc/service.ts +localOnly
+Input:
+file @svc/service.ts
 file src/index.ts
-
-inspect file src/service.ts [--ranges] [--local-only]

package/dist/help/topics/inspect.graph.md

@@ -64,11 +64,10 @@ Use DSL or request flags to hide sections such as edges/hubs/entrypoints/leaves.
 
 Specialized graph command:
 Run:
-aib inspect graph --stdin
+aib inspect graph @svc --view local --save services-graph
 
-Input:
-graph scope=@svc view=local >services-graph
-graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbolUsage -edges
+Focus saved graph:
+aib inspect graph --from-file aib:graph:services-graph --focus @svc/users.ts --focus @svc/admins.ts --symbol-usage
 
 Multiple scopes:
 Run:
@@ -86,19 +85,6 @@ aib inspect --stdin
 Input:
 graph scope=src view=local exclude=["**/*.test.ts","**/* copy.ts"] >src-graph
 
-Graph prefs:
-inspect.graph.edges boolean
-inspect.graph.hubs boolean
-inspect.graph.entrypoints boolean
-inspect.graph.leaves boolean
-inspect.graph.symbols boolean
-inspect.graph.symbolUsage boolean
-
-symbolUsage is usually the better first choice when imported names matter.
-
-Example:
-session prefs set inspect.graph.edges false inspect.graph.hubs false inspect.graph.symbolUsage true
-
 Output fields:
 summary       file/edge/package counts
 paths         compact path aliases used in text output

package/dist/help/topics/{inspect.md → inspect.shared.md}

@@ -9,18 +9,19 @@ map: learn what exists and how it connects
 focus: choose files/entities/usages that matter
 code: fetch exact code needed
 
-Choose inspect operation:
-
-declarations in one file         file
-static/dynamic imports           imports
-public API                       exports
-methods/properties of parent     members
-exact implementation             code
-outgoing deps of one entity      deps
-incoming references/callers      usages
-file/module connectivity         graph
-compact directory layout         tree
-repeated declarations/helpers    duplicates
+Choose inspect operation:
+
+declarations in one file         file
+static/dynamic imports           imports
+public API                       exports
+methods/properties of parent     members
+exact implementation             code
+outgoing deps of one entity      deps
+incoming references/callers      usages
+file/module connectivity         graph
+compact directory layout         tree
+path alias candidates            aliasCandidates
+repeated declarations/helpers    duplicates
 local import cycles              cycles
 
 Prefer one batch DSL request for related questions.

package/dist/help/topics/modulePlan.md

@@ -1,41 +1,36 @@
-Modes: preview/apply or execute.
-Use execute for routine changes.
-Use preview/apply when learning a mutation command or inspecting a large multi-step request before writing files.
+Run mutation DSL through aib mutate.
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
 
 If a name is ambiguous, use selectors.
 Run help selectors to refresh selector syntax.
 
-modulePlan is for splitting large files into smaller modules.
-Use it when a large file should be refactored into several target files.
-
-modulePlan orchestrates semantic moves and updates affected references/imports.
-
-If imports created by modulePlan do not match the repo style, run:
-aib help config-setup.import-rules
+Use module only for a full-file split: moving all declarations from one source file into target modules.
+Do not mix module with other mutation operations.
 
 Use +expectEmpty when your modulePlan intent is to move all declarations out of the source file.
 It does not change the move behavior; it only asks output to report remaining source declarations if any remain.
 Use it only when remaining declarations would mean the split did not match your intent.
 Do not use it for partial extractions.
 
-Plan:
-modulePlan preview --stdin
-modulePlan execute --stdin
-modulePlan apply <planId>
-
-Use preview/apply when you want to inspect the plan before writing files.
-Use execute when you want to preview and apply immediately.
+Focused syntax:
+module <targetFile>: <entity...>
+
+Split one large source file into several targets:
+Run:
+aib mutate execute --stdin
 
-Split one large source file into several targets:
-Run:
-aib modulePlan execute --stdin
-
 Input:
 @source src/large-service.ts +expectEmpty
 module src/large-service.types.ts: ServiceOptions ServiceMode
-module src/large-service.core.ts: LargeService createLargeService
-
-How inheritance works above:
-@source sets the source file once.
-+expectEmpty says no declarations should remain in the source after the plan.
+module src/large-service.core.ts: LargeService createLargeService
+
+How inheritance works above:
+@source sets the source file once.
++expectEmpty says no declarations should remain in the source after the plan.
 Each module line declares one target and the entities that should move there.

package/dist/help/topics/move.md

@@ -1,30 +1,29 @@
-Modes: preview/apply or execute.
-Use execute for routine changes.
-Use preview/apply when learning a mutation command or inspecting a large multi-step request before writing files.
+Run mutation DSL through aib mutate.
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
 
 If a name is ambiguous, use selectors.
 Run help selectors to refresh selector syntax.
 
-Move transfers one or more symbols from one file to another.
-Move is semantic; it moves supported declarations and updates affected imports/references.
-Use it for focused extraction into a single target file.
-For large file splitting across several target files, use modulePlan.
+Move transfers declarations from one source file to target files.
+Move is semantic; it moves supported declarations and updates affected imports/references.
+Use move as the default operation for moving declarations, including multi-target extractions.
 
 If imports created by move do not match the repo style, run:
 aib help config-setup.import-rules
 
-Move to file:
-move toFile preview --stdin
-move toFile execute --stdin
-move toFile apply <previewId>
-
-Use preview/apply when you want to inspect the planned change before writing files.
-Use execute when you want to write immediately.
+Syntax:
+move <targetFile>: <entity...>
+
+Run:
+aib mutate execute --stdin
 
-Move several entities into one target:
-Run:
-aib move toFile execute --stdin
-
 Input:
 @source src/service.ts
 move src/service.helpers.ts: oldHelper OtherHelper
+move src/service.types.ts: ServiceOptions

package/dist/help/{dsl/docs/file.move.md → topics/moveToDir.md}

@@ -1,46 +1,44 @@
-# File Move
+Run mutation DSL through aib mutate.
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
 
-Modes: preview/apply or execute.
-Use execute for routine changes.
-Use preview/apply when learning a mutation command or inspecting a large multi-step request before writing files.
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
 
-file move moves whole files into target directories.
+moveToDir moves whole files into target directories.
 Missing target directories are created automatically.
 
 Use it when the filesystem layout is the intent.
 
-Move to directory:
-file move toDir preview --stdin
-file move toDir execute --stdin
-file move toDir apply <previewId>
-
-Use preview/apply when you want to inspect planned file moves before writing files.
-Use execute when you want to write immediately.
+Syntax:
+moveToDir <targetDir>: <file...>
 
 Run:
-aib file move toDir execute --stdin
-
-Input:
-@base src/svc
-moveToDir facade: ../services/fileA.ts fileB.ts
-moveToDir ../core/services: fileC.ts classes/main/fileD.ts
-
-How this resolves:
-../services/fileA.ts resolves to src/services/fileA.ts
-fileB.ts resolves to src/svc/fileB.ts
-facade resolves to src/svc/facade
-../core/services resolves to src/core/services
+aib mutate execute --stdin
+
+Input:
+@base src/svc
+moveToDir facade: ../services/fileA.ts fileB.ts
+moveToDir ../core/services: fileC.ts classes/main/fileD.ts
+
+How this resolves:
+../services/fileA.ts resolves to src/services/fileA.ts
+fileB.ts resolves to src/svc/fileB.ts
+facade resolves to src/svc/facade
+../core/services resolves to src/core/services
 moved files keep their basename, not their source subdirectory
-
-Resulting files:
-src/svc/facade/fileA.ts
-src/svc/facade/fileB.ts
-src/core/services/fileC.ts
+
+Resulting files:
+src/svc/facade/fileA.ts
+src/svc/facade/fileB.ts
+src/core/services/fileC.ts
 src/core/services/fileD.ts
 
-Rules:
-- @base sets the base directory for source files and target directories.
-- source file paths resolve from @base; cwd-relative paths are accepted when the @base path does not exist.
-- target directories resolve from @base.
-- source paths and target directories may use `..`.
-- file move supports files, not directories.
+Rules:
+- @base sets the base directory for source files and target directories.
+- source file paths resolve from @base; cwd-relative paths are accepted when the @base path does not exist.
+- target directories resolve from @base.
+- source paths and target directories may use `..`.
+- moveToDir supports files, not directories.

package/dist/help/topics/mutate.mixed.md

@@ -0,0 +1,32 @@
+Run mutation DSL through aib mutate.
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
+
+If a name is ambiguous, use selectors.
+Run help selectors to refresh selector syntax.
+
+Use one mutate request for one ordered workflow.
+Mix rename, move, moveToDir, and renameFile when they belong to the same workflow.
+Order lines the way the workflow should run.
+Do not include module lines in mixed requests.
+
+Run:
+aib mutate execute --stdin
+
+Input:
+@source src/service.ts
+rename oldHelper->newHelper AUser->AdminUser
+move src/service.helpers.ts: newHelper
+move src/service.types.ts: AdminUser
+
+@base src/main
+moveToDir facade: ../services/fileA.ts fileB.ts
+moveToDir ../core/services: fileC.ts classes/main/fileD.ts
+
+@base src
+renameFile svc/ws-cli.ts->cli.ts svc/ws-command.ts->command.ts

package/dist/help/topics/mutation.shared.md

@@ -0,0 +1,53 @@
+Mutation commands change code and files through TS/IDE-backed operations.
+Successful mutations update affected references and imports.
+
+Semantic mutations change TypeScript symbols/declarations.
+File mutations change file layout.
+
+After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or checks show a real issue.
+
+If mutation imports do not match the repo style, run:
+aib help config-setup.import-rules
+
+AIB mutations are designed to reduce manual checking.
+Your job is to express the intent in DSL.
+AIB's job is to convert that intent into code changes.
+
+The DSL inside the request describes the intent:
+rename      rename TypeScript symbols
+move        move TypeScript declarations into target files
+moveToDir   move whole files into directories
+renameFile  rename whole files
+module      full-file split: move all declarations from one source into target modules
+
+Mix rename, move, moveToDir, and renameFile when they belong to the same workflow.
+Run module splits as a separate mutate request.
+
+Do not read all changed files just because a mutation touched them.
+That defeats the purpose of using AIB for mechanical refactors.
+
+When the command completes, use its output as the source of truth for what changed and what remains.
+After failure or partial success, use the output to decide the next request.
+
+Set the command timeout to 5 minutes for AIB requests.
+If the harness stops waiting before final output appears, recover with:
+
+aib execution status last
+
+Modes:
+preview  review DSL intent, then apply by id
+apply    execute from preview
+execute  execute immediately
+
+Use preview/apply when you are learning a mutation command.
+Use execute for routine requests.
+
+preview/apply uses more tool calls and more output tokens.
+preview checks the DSL intent; execute/apply writes files and can still hit mutation errors.
+execute writes immediately and reports what changed.
+
+Prefer one mutate DSL request for related changes.
+For mixable operations, batch the ordered workflow instead of sending one command per symbol or file.
+
+If a mutation cannot be fully completed, aib reports what failed, what was applied, and what did not run.
+Fix wrong input before retrying; do not repeat provider/manual-extraction failures unchanged.

package/dist/help/topics/patterns.md

@@ -1,18 +1,9 @@
 To refresh help protocol:
 aib help help-protocol
 
-Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
-Use qr for cross-OS quick reads of text files, logs, JSON, scripts, and line windows.
-It is not a replacement for inspect.
-Use normal text search when the question is just text.
-
-For a first pass in a new codebase, map directories before reading files:
+Working patterns
 
-aib inspect tree src --depth 5 --only-dirs --limit 200
-
-Start compact for broad scans.
-Use summary, locations, or local graph views first when output could be large.
-Expand to code or wider graph views only for the parts that matter now.
+Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
 If output hides data and shows `view: aib:res_<id>`, use `aib view ...` to fetch only the hidden part instead of repeating the original request.
 
 Compact output is a starting point, not a substitute for needed code.
@@ -33,7 +24,7 @@ That defeats the purpose of using AIB for mechanical refactors.
 If the command succeeds, the requested mechanical change was applied.
 After failure or partial success, use the output to decide the next request.
 
-For mutation commands, set the shell/tool harness timeout to 3 minutes.
+Set the command timeout to 5 minutes for AIB requests.
 
 If a mutation command times out or returns no final output, use:
 

package/dist/help/topics/qr.md

@@ -2,19 +2,25 @@ Use qr for cross-OS quick reads of text files: ts, js, cmd, sh, json, log, txt,
 Use it for compact line windows and batching.
 qr supports AIB path aliases.
 
-It is not a replacement for inspect.
+It is not a replacement for aib inspect in TS/JS cases.
 Use it as a token-efficient way to read text data when semantic inspect is not needed.
 
 For focused text reads, prefer qr over cat/Get-Content/type, especially when aliases, line windows, or batching help.
 Use shell reads only when piping into shell tooling or qr is unavailable.
 
 Controls:
-h=N        head; first N lines
-t=N        tail; last N lines
-o=N l=N    range; starting line and line count
-all        whole file
+h=N              head; first N lines
+t=N              tail; last N lines
+r=A:B,C:D,E      ranges; A with next B lines, C with next D lines, E with default 80 lines
+s=A:B,C:D,E      slices; inclusive A through B, C through D, and line E
+all              whole file
 
 If no window is provided, qr uses h=80.
-If all is present, it wins over other window flags.
+If all is present, it reads the whole file.
+Avoid `all` for files whose size/content is unknown; it can dump unnecessary context.
+Overlapping windows are merged.
+
+Use s= when copying ranges from inspect file.
+Combine windows for the same file instead of repeating the path.
 
 {{qr.inline.examples}}