@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/help/docs/move.md

@@ -1,40 +1,37 @@
 # Move
 
-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
 
 Move creates the target file when needed.
 The target can already exist.
 
-The request means:
-take entities from sourceFile and move them into targetFile.
-
-Use refactor batch when the same workflow needs both rename and move steps.
+The request means:
+take entities from sourceFile and move them into targetFile.

package/dist/help/docs/moveToDir.md

@@ -0,0 +1,46 @@
+# MoveToDir
+
+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/docs/mutate.mixed.md

@@ -0,0 +1,34 @@
+# Mixed Mutation
+
+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/docs/mutation.shared.md

@@ -0,0 +1,55 @@
+# Mutation
+
+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/docs/patterns.md

@@ -3,27 +3,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
@@ -39,7 +26,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/docs/qr.md

@@ -4,34 +4,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/docs/quick-map.md

@@ -1,30 +1,43 @@
 # Quick Map
 
-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/docs/recipe.file-layout.md

@@ -0,0 +1,15 @@
+# File Layout Recipe
+
+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/docs/recipe.import-boundary.md

@@ -0,0 +1,92 @@
+# Import Boundary Recipe
+
+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/docs/recipe.safe-artifact-probing.md

@@ -0,0 +1,68 @@
+# Safe Artifact Probing Recipe
+
+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.

package/dist/help/docs/recipe.unfamiliar-area.md

@@ -0,0 +1,64 @@
+# Unfamiliar Area Recipe
+
+The same task can be solved with broad output dumps or with structured narrowing.
+Use this recipe to spend context on signal: boundaries, candidate files, then exact slices.
+
+Start with directory structure and boundaries.
+Use `inspect.tree` with directories first:
+
+tree <scope> depth=3 +onlyDirs limit=120
+
+If the task explicitly requires a hidden/dependency/vendor/generated area, keep the scope narrow and only then disable excludes:
+
+tree <narrow-scope> depth=3 +onlyDirs limit=120 +ned +nec
+
+Do not start with broad `+ned +nec` over the repo root.
+
+Localize candidate files.
+If you have a concrete term, symbol, package name, error text, import specifier, or config key, use count search before full match output:
+
+aib rg -- -c "<pattern>" <scope>
+
+Use counts to pick a small set of candidate files before reading matches or file content.
+
+If you do not have a concrete search pattern yet, inspect the file layout instead of inventing broad patterns:
+
+tree <narrow-scope> depth=4 only=["**/*.ts","**/*.tsx","**/*.js","**/*.json"] limit=160
+
+Use the file layout to pick likely files or narrower directories, then continue with focused inspect or focused search.
+
+Map candidate files before implementation reads.
+For TS/JS candidates, inspect the strongest candidates first.
+
+Run:
+aib inspect --stdin
+
+Input:
+file <candidate-a.ts>
+file <candidate-b.ts>
+
+Use file output for declarations and ranges.
+
+Add imports only when dependency, wrapper, source, or "where does this come from" questions matter:
+
+imports <candidate-a.ts>
+
+Add exports only for public module surface, barrels, re-exports, export *, or boundary questions:
+
+exports <candidate-index.ts> +resolveStar
+
+Then read exact implementation slices with qr:
+
+aib qr <candidate-a.ts> s=<range-a>,<range-b>
+
+For non-TS/JS candidates, start with small qr windows:
+
+aib qr <candidate> h=80
+
+Then narrow with `s=` or `r=` as needed.
+Avoid `all` for files whose size/content is unknown.
+
+Read implementation only after you have a narrowed scope, candidate files, and ranges or windows.
+
+Focused help:
+aib help inspect.tree inspect.file inspect.imports inspect.exports qr rg

package/dist/help/docs/recipes.md

@@ -0,0 +1,20 @@
+# Recipe Router
+
+Run as:
+aib help <recipe...>
+
+Read and use a recipe when one of these situations appears during regular work.
+
+Opportunistic triggers:
+
+- Trigger: you create, change, or adopt a barrel/import boundary
+  Read: recipe.import-boundary
+
+- Trigger: you are about to change file layout, move files, or rename files
+  Read: recipe.file-layout
+
+- Trigger: you are about to debug, modify, or extend code in an unfamiliar area
+  Read: recipe.unfamiliar-area
+
+- Trigger: you are about to run a tool or runtime probe against a generated, bundled, minified, dependency/vendor, lock/patch, or huge-line artifact
+  Read: recipe.safe-artifact-probing

package/dist/help/docs/rename.md

@@ -1,8 +1,13 @@
 # Rename
 
-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.
@@ -11,29 +16,16 @@ Rename is for semantic symbol renames.
 It follows TypeScript references.
 It is not plain-text replacement.
 
-Single rename:
-rename preview <file> <entity> <newName>
-rename execute <file> <entity> <newName>
-rename apply <previewId>
-
-Use preview/apply when you want to inspect the planned change before writing files.
-Use execute when you want to write immediately.
-
-Run:
-aib rename execute --stdin
-
-Input:
-@file src/service.ts
+Syntax:
+rename <oldName>-><newName> <oldName2>-><newName2>
+
+Run:
+aib mutate execute --stdin
+
+Input:
+@source src/service.ts
 rename oldName->newName OldService->NewService
 
-Rename can use plain names or selectors.
-For methods and properties, use parent-qualified syntax when needed:
-rename Service.oldMethod->newMethod
-
-Single rename:
-rename preview <file> <entity> <newName>
-rename execute <file> <entity> <newName>
-rename apply <previewId>
-
-Use preview/apply when you want to inspect the planned change before writing files.
-Use execute when you want to write immediately.
+Rename can use plain names or selectors.
+For methods and properties, use parent-qualified syntax when needed:
+rename Service.oldMethod->newMethod