@automaton-labs/aib 0.0.6 → 0.0.8

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

@@ -9,33 +9,34 @@ 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.
 
 Batch example:
-
-Run:
-aib inspect --stdin
-
+
+Run:
+aib inspect --stdin
+
 Input:
 @file @svc/service.ts
 file
 file @svc/serviceB.ts
 members Service
-code entities=[Service.{render,reset},normalize]
+code entities=[Service.{render,reset},normalize,default,IIFE#1]
 code @svc/serviceC.ts ServiceC -ranges
 usages target=@svc/service.ts normalize scope=src detail=loc
 duplicates scope=src/scripts detail=sum limit=20

package/dist/help/dsl/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/dsl/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/topics/moveToDir.md

@@ -0,0 +1,44 @@
+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>
+
+moveToDir moves whole files into target directories.
+Missing target directories are created automatically.
+
+Use it when the filesystem layout is the intent.
+
+Syntax:
+moveToDir <targetDir>: <file...>
+
+Run:
+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
+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 `..`.
+- moveToDir supports files, not directories.

package/dist/help/dsl/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/dsl/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/dsl/topics/patterns.md

@@ -1,27 +1,14 @@
 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:
-
-tree src depth=5 +onlyDirs limit=200
+Working patterns
 
-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.
 Fetch exact code when correctness depends on implementation details.
 
-Use prefs when the current phase repeats the same output shape.
-Turn details off when they stop helping.
-Turn them back on when they matter.
-
 Use @file only when several following operations share the same file.
 For independent one-off file requests, pass the path directly:
 file @svc/a.ts
@@ -37,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/dsl/topics/qr.md

@@ -2,34 +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    offset; starting line, 1-based
--l N    limit; line count for offset reads
--a      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 -a is present, it wins over other window flags.
+If no window is provided, qr uses h=80.
+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.
 
-Run:
-aib qr --stdin
+Use s= when copying ranges from inspect file.
+Combine windows for the same file instead of repeating the path.
 
-Input:
-qr @scripts/a.txt h=80
-qr @scripts/b.py o=300 l=50
-qr @scripts/c.md t=120
-qr @logs/app.log all
-
-Inline:
-aib qr @scripts/a.txt -h 80
-aib qr @scripts/b.py -o 300 -l 50
-aib qr @logs/app.log -a
-
-Use stdin for several reads.
+{{qr.inline.examples}}

package/dist/help/dsl/topics/quick-map.md

@@ -1,28 +1,41 @@
-Read:
-  qr              quick reads: ts, js, cmd, sh, json, log, txt, etc.
-  view            hidden/truncated output
+Run as: aib help <topic...>
 
-Inspect:
-  file
-  imports
-  exports
-  members
-  code
-  deps
-  usages
-  graph
-  tree
-  duplicates
-  cycles
+Help conventions:
+  help-format
 
-Mutate:
+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.duplicates
+  inspect.cycles
   rename
   move
+  moveToDir
+  renameFile
+  mutate.mixed        batch related mutation steps
   modulePlan
-  refactor batch
-  imports normalize
-
-Other:
-  config
-  prefs
-  reveal         tsconfig and tsconfig alias discovery
+  import.rebase
+  imports.normalize
+  view
+  qr
+  rg
+  reveal              tsconfig and tsconfig alias discovery

package/dist/help/dsl/topics/recipe.file-layout.md

@@ -0,0 +1,13 @@
+Assumption:
+You are changing whole-file layout.
+You are not moving TypeScript declarations or renaming TypeScript symbols.
+
+Related topics:
+aib help mutation moveToDir renameFile
+
+If you only need to move files, do not read renameFile.
+If you only need to rename files, do not read moveToDir.
+
+Use focused topic syntax to express the file layout refactor.
+Do not move or rename files manually.
+Use AIB file mutations so references/imports are updated.

package/dist/help/dsl/topics/recipe.import-boundary.md

@@ -0,0 +1,90 @@
+Assumption:
+You are changing import boundaries, not only import style.
+
+Goal:
+Move eligible consumers toward or away from a barrel boundary.
+
+Choose direction:
+- useBarrel when a barrel should become the import boundary.
+- useDirect when consumers should stop importing through that barrel.
+
+Optional limits:
+Use the controls below only when the migration is intentionally partial.
+
+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.
+
+Split the migration only when different consumer areas need different boundaries,
+or when part of the repo should intentionally stay unchanged for this pass.

package/dist/help/dsl/topics/recipe.safe-artifact-probing.md

@@ -0,0 +1,66 @@
+You are about to run a tool, runtime, parser, compiler, formatter, linter, `require`, or `vm` probe against a generated, bundled, minified, dependency/vendor, lock/patch, or huge-line artifact.
+
+Do not print raw probe output directly.
+Capture stdout/stderr first, then read only a small byte-capped diagnostic.
+
+Run the probe into files:
+
+`<probe command> > <tmp-out> 2> <tmp-err>`
+
+Print status separately.
+Read a small byte-capped diagnostic from stderr.
+
+Example:
+
+`head -c 2000 <tmp-err>`
+
+Use an equivalent byte-capped read for the current shell when `head -c` is unavailable.
+
+Do not use line count as the safety boundary for unknown huge-line output.
+`tail -40` can still print a huge bundled source line.
+
+If the diagnostic is mostly raw source context, do not increase the cap.
+Change the probe shape.
+
+Use the diagnostic signal to narrow the next step:
+- exit code;
+- error name;
+- error message;
+- short stack frames;
+- path, line, symbol, option, or short literal.
+
+If the task is still "where is the relevant code?", use `recipe.unfamiliar-area` first.
+Return here before running a risky parser/runtime/tool probe.
+
+For JavaScript parse-only questions, prefer a syntax check before runtime execution:
+
+`node -c <artifact> > <tmp-out> 2> <tmp-err>`
+
+For JavaScript runtime questions, catch exceptions and print structured fields instead of raw stacks.
+
+Print:
+- error name;
+- error message;
+- a small number of short stack-frame-looking lines.
+
+Do not print raw `e.stack` for generated, bundled, minified, dependency/vendor, or huge-line artifacts.
+
+Example shape:
+
+```js
+try {
+  // run the smallest runtime probe that answers the question
+} catch (e) {
+  console.error(`${e?.name || "Error"}: ${e?.message || ""}`);
+  for (const line of String(e?.stack || "").split(/\r?\n/)) {
+    const text = line.trim();
+    if (text.startsWith("at ") && text.length < 500) {
+      console.error(text);
+    }
+  }
+  process.exitCode = 1;
+}
+```
+
+After a small diagnostic, continue with narrow reads/searches.
+Read artifact implementation only after the diagnostic points to a specific term, range, wrapper, entrypoint, or behavior.