@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/help/dsl/help-index.md

@@ -0,0 +1,49 @@
+Run as: aib help <topic...>
+
+Start here if this is your first AIB pass:
+  bootstrap
+
+Always after context compaction:
+  aib help help-protocol quick-map recipes rules
+  aib config aliases
+
+Help conventions:
+  help-format
+
+Refresh workflow model:
+  basics patterns
+
+Core focused topics:
+  session
+  rules
+  selectors
+  dsl
+  inspect.shared
+  mutation.shared
+  recipes
+
+Feature topics:
+  inspect.file
+  inspect.imports
+  inspect.exports
+  inspect.members
+  inspect.code
+  inspect.deps
+  inspect.usages
+  inspect.graph
+  inspect.tree
+  inspect.aliasCandidates
+  inspect.duplicates
+  inspect.cycles
+  rename
+  move
+  moveToDir
+  renameFile
+  mutate.mixed
+  modulePlan
+  import.rebase
+  imports.normalize
+  view
+  qr
+  rg
+  reveal

package/dist/help/dsl/snippets/agents.md

@@ -10,5 +10,5 @@ Use {{docsPath}} when working with TS/JS code.
 Help fallback:
 For TS/JS code work, use aib. Start with {{docsPath}}. If local docs are not enough, run `aib help bootstrap`.
 
-Refactor-focused:
-When changing TS/JS code, use aib for semantic discovery, usages, graph, rename, move, and modulePlan. Start with {{docsPath}}.
+Refactor-focused:
+When changing TS/JS code, use aib for semantic discovery, usages, graph, and mutate DSL. Start with {{docsPath}}.

package/dist/help/dsl/tokens/qr.inline.examples.md

@@ -0,0 +1,2 @@
+Inline:
+aib qr @svc/users.ts s=3:42,66:84,92 @scripts/a.txt h=80 @scripts/b.py r=300:50,500 .prettierrc all

package/dist/help/dsl/tokens/stdin.examples.bash.md

@@ -0,0 +1,8 @@
+Bash/Zsh:
+aib <command> --stdin <<'EOF'
+<input>
+EOF
+
+aib inspect --stdin <<'EOF'
+tree . +onlyDirs limit=20
+EOF

package/dist/help/dsl/tokens/stdin.examples.pwsh.md

@@ -0,0 +1,8 @@
+PowerShell:
+@'
+<input>
+'@ | aib <command> --stdin
+
+@'
+tree . +onlyDirs limit=20
+'@ | aib inspect --stdin

package/dist/help/dsl/tokens/stdin.examples.with-qr.bash.md

@@ -0,0 +1,12 @@
+Bash/Zsh:
+aib <command> --stdin <<'EOF'
+<input>
+EOF
+
+aib inspect --stdin <<'EOF'
+tree . +onlyDirs limit=20
+EOF
+
+aib qr --stdin <<'EOF'
+qr package.json h=20
+EOF

package/dist/help/dsl/tokens/stdin.examples.with-qr.pwsh.md

@@ -0,0 +1,12 @@
+PowerShell:
+@'
+<input>
+'@ | aib <command> --stdin
+
+@'
+tree . +onlyDirs limit=20
+'@ | aib inspect --stdin
+
+@'
+qr package.json h=20
+'@ | aib qr --stdin

package/dist/help/dsl/topics/basics.md

@@ -8,5 +8,5 @@ Prefer batch DSL instead of one-off inline calls.
 One request can inspect/mutate several files/entities and save reusable artifacts when supported.
 Use one-off commands only for small checks/changes.
 
-For mutations, aib asks TS/IDE refactors to update affected references and imports.
+For mutations, aib asks TypeScript semantic refactors to update affected references and imports.
 After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or the build/checks show a real issue.

package/dist/help/dsl/topics/config-setup.import-normalize.md

@@ -1,18 +1,18 @@
-Configure import normalization intent.
-
-importNormalize defines default normalization rules for explicit aib imports normalize commands.
-Use it before broad or important import cleanup so the scope, target style, preferred alias, and excludes are stored in aib.json instead of repeated in command arguments.
-
-It does not run automatically during move/modulePlan.
-Use importRules for mutation-time import cleanup.
-
-Set importNormalize when the intended cleanup has project meaning:
-- adopting a new tsconfig alias across a project area;
-- converting an area to aliases;
-- converting scripts/tools or extracted modules to relative imports;
-- excluding generated or bundled output from normalization.
-
-For tiny one-file checks, inline options are fine.
+Configure import normalization intent.
+
+importNormalize defines default normalization rules for explicit aib imports normalize commands.
+Use it before broad or important import cleanup so the scope, target style, preferred alias, and excludes are stored in aib.json instead of repeated in command arguments.
+
+It does not run automatically during move/modulePlan.
+Use importRules for mutation-time import cleanup.
+
+Set importNormalize when the intended cleanup has project meaning:
+- adopting a new tsconfig alias across a project area;
+- converting an area to aliases;
+- converting scripts/tools or extracted modules to relative imports;
+- excluding generated or bundled output from normalization.
+
+For tiny one-file checks, inline options are fine.
 Before wider cleanup, put the intended rule in config and preview the smallest useful scope.
 
 Fields:
@@ -29,56 +29,56 @@ shortestAlias  rewrite to the shortest valid alias specifier
 preferAlias:
 @shared/*      prefer one alias pattern when several aliases can resolve the same file
 
-Alias cleanup:
-
-"importNormalize": [
-  {
-    "scope": "src",
-    "to": "shortestAlias",
-    "preferAlias": "@/*",
-    "exclude": [
-      "src/generated",
-      "src/**/dist"
-    ]
-  }
+Alias cleanup:
+
+"importNormalize": [
+  {
+    "scope": "src",
+    "to": "shortestAlias",
+    "preferAlias": "@/*",
+    "exclude": [
+      "src/generated",
+      "src/**/dist"
+    ]
+  }
+]
+
+Relative cleanup for scripts/tools:
+
+"importNormalize": [
+  {
+    "scope": "scripts",
+    "to": "relative",
+    "exclude": [
+      "scripts/**/*.cjs",
+      "scripts/**/*.mjs"
+    ]
+  }
 ]
 
-Relative cleanup for scripts/tools:
-
-"importNormalize": [
-  {
-    "scope": "scripts",
-    "to": "relative",
-    "exclude": [
-      "scripts/**/*.cjs",
-      "scripts/**/*.mjs"
-    ]
-  }
-]
-
-If you have not just checked config rules, run:
-
-aib config rules
-
-After editing aib.json, run:
-
-aib sync
-
-Then preview the smallest useful scope before applying:
-
-aib imports normalize preview <scope>
-
-Preview shows counts, sample import rewrites, a planId, and the apply command.
-It does not change project files.
-
-If preview changes imports outside the intended area, narrow scope or add exclude.
-
-If preview does not use the expected alias, check tsconfig aliases:
-
-aib reveal tsaliases
-
-If the config and aliases look correct but preview still looks stale or strange, run:
-
-aib sync
-
+If you have not just checked config rules, run:
+
+aib config rules
+
+After editing aib.json, run:
+
+aib sync
+
+Then preview the smallest useful scope before applying:
+
+aib imports normalize preview <scope>
+
+Preview shows counts, sample import rewrites, a planId, and the apply command.
+It does not change project files.
+
+If preview changes imports outside the intended area, narrow scope or add exclude.
+
+If preview does not use the expected alias, check tsconfig aliases:
+
+aib reveal tsaliases
+
+If the config and aliases look correct but preview still looks stale or strange, run:
+
+aib sync
+
 Then preview again.

package/dist/help/dsl/topics/config-setup.import-rules.md

@@ -7,11 +7,12 @@ Check current config:
 
 aib config 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/dsl/topics/dsl.md

@@ -8,9 +8,10 @@ DSL request model:
 - For one-off file operations, pass the path directly.
 
 Syntax:
-@file <path>               default file
-@source <path>             default sourceFile for mutations
-op arg arg key=value       request
+@file <path>               default file
+@source <path>             default sourceFile for mutations
+@base <dir>                default base dir for file mutations
+op arg arg key=value       request
 +flag                      boolean true
 -flag                      boolean false
 >name                      save reusable artifact when supported

package/dist/help/dsl/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/dsl/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/dsl/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/dsl/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/dsl/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/dsl/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, or declaration
-- 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
@@ -19,9 +13,9 @@ Use -ranges for source without ranges.
 Prefs:
 inspect.code.maxNonEmptyLines
 
-Run:
-aib inspect --stdin
-
+Run:
+aib inspect --stdin
+
 Input:
 code @svc/service.ts Service.{render,reset} normalize
-code @svc/serviceB.ts ServiceB.{constructor}
+code @svc/serviceB.ts ServiceB.{constructor} default IIFE#1

package/dist/help/dsl/topics/inspect.deps.md

@@ -1,18 +1,18 @@
 Use deps to see what one entity depends on inside its file.
 It separates type-only dependencies from runtime value dependencies.
 
-Good for:
-- checking what a symbol may need when moved or extracted
-- spotting nearby types, constants, or helpers tied to one entity
-- deciding whether one symbol is standalone or tied to nearby declarations
+Good for:
+- checking what a symbol may need when moved or extracted
+- spotting nearby types, constants, or helpers tied to one entity
+- deciding whether one symbol is standalone or tied to nearby declarations
 - debugging mutation failures caused by local dependency shape
 
 Controls:
 file, entity, entities, parent
 
-Run:
-aib inspect --stdin
-
+Run:
+aib inspect --stdin
+
 Input:
 deps @svc/service.ts entities=[createService,normalize,Service.{render,reset}]
 deps @svc/serviceB.ts ServiceB.{constructor} getConfig

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

@@ -2,29 +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 an unfamiliar file
-- listing top-level declarations
+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/dsl/topics/inspect.graph.md

@@ -35,7 +35,7 @@ scope=src creates a broad reusable map for src.
 scope=src/services is cheaper for local work.
 scope=[src/services,src/components] compares known areas without mapping all src.
 
-After you understand which graph sections matter, hide the rest with flags or prefs.
+After you understand which graph sections matter, hide the rest with flags.
 Graph can be noisy; shape it for the current task.
 
 Controls:
@@ -59,16 +59,15 @@ graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbol
 Focus saved graph later:
 inspect graph --from-file aib:graph:services-graph --focus @svc/messages.ts --focus @svc/posts.ts --symbol-usage
 
-Inline graph focus can add focus and symbolUsage.
-Use DSL, request files, or prefs to hide sections such as edges/hubs/entrypoints/leaves.
+Inline graph focus can add focus and symbolUsage.
+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