@automaton-labs/aib 0.0.5 → 0.0.7

package/dist/help/dsl/full.md

@@ -6,20 +6,17 @@ It can inspect symbols, usages, dependencies, duplicates, focused code, and run
 aib is designed for agent workflows:
 batch requests, compact text output, session handles, and reusable artifacts.
 
-Inline commands omit the aib prefix.
-When you see:
-session prefs get
-
-Run:
-aib session prefs get
-
-Stdin examples show command and input separately to avoid shell-specific syntax.
-Stdin Run lines include the aib prefix to avoid confusion.
+Inline commands omit the aib prefix.
+When you see:
+session clear
+
+Run:
+aib session clear
 
-PowerShell stdin shape:
-@'
-<input>
-'@ | aib <command> --stdin
+Stdin examples show command and input separately to avoid shell-specific syntax.
+Stdin Run lines include the aib prefix to avoid confusion.
+
+{{stdin.examples}}
 
 Basics
 
@@ -62,7 +59,7 @@ 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
+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.
@@ -72,10 +69,6 @@ If output hides data and shows `view: aib:res_<id>`, use `aib view ...` to fetch
 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.
-
 For mutation commands, set the shell/tool harness timeout to 3 minutes.
 
 If a mutation command times out or returns no final output, use:
@@ -101,7 +94,7 @@ If move/modulePlan imports do not match the repo style, run:
 aib help config-setup.import-rules
 
 If you are about to change import style across files, add or adopt tsconfig aliases, or clean imports repeatedly, run:
-aib help config-setup.import-normalize
+aib help config-setup.import-normalize imports.normalize
 
 If tree/graph output includes known repo noise, run:
 aib help config-setup.excludes
@@ -196,7 +189,7 @@ Start by creating or selecting your session.
 Create it once, then reuse it.
 Do not create a new session for every command or subtask.
 
-Session stores saved artifacts, aliases, and prefs.
+Session stores saved artifacts and aliases.
 
 Prefer short session names:
 aa, tr, qa, a2
@@ -224,39 +217,6 @@ Reusable index handles look like:
 
 Pass index handles back to the matching inspect command with `--from-file` or `from` in DSL.
 
-Prefs
-
-Prefs change defaults for the active session.
-Use them when you want repeated CLI behavior without repeating request fields.
-
-Set prefs:
-session prefs set <name> <value> [<name> <value>...]
-
-Example:
-session prefs set inspect.graph.hubs false inspect.graph.leaves false
-
-Show prefs:
-session prefs get [prefix] [--all]
-
-By default, get shows session overrides.
---all includes defaults.
-prefix filters keys.
-
-boolean = true|false
-N = integer
-
-Available prefs:
-inspect.code.maxNonEmptyLines N
-inspect.usages.maxLocations N
-inspect.usages.maxCodeBlocks N
-inspect.members.maxItems N
-inspect.members.all boolean
-inspect.graph.hubs boolean
-inspect.graph.entrypoints boolean
-inspect.graph.leaves boolean
-inspect.graph.edges boolean
-inspect.graph.symbolUsage boolean
-
 Selectors identify symbols when names are ambiguous.
 Use plain names when they are unambiguous.
 Use selectors when aib reports ambiguity or when different symbol kinds share a name.
@@ -275,8 +235,9 @@ c-Name  class
 i-Name  interface
 t-Name  type
 v-name  variable
-e-Name  enum
-m-name  method, usually with parent
+e-Name  enum
+ns-Name namespace
+m-name  method, usually with parent
 p-name  property, usually with parent
 
 DSL request model:
@@ -289,9 +250,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
@@ -336,16 +298,16 @@ aib help inspect.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
@@ -386,8 +348,9 @@ 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
+- 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.
@@ -490,7 +453,7 @@ 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
+- 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
 
@@ -504,30 +467,30 @@ Defaults: +show +ranges
 Use -show for names/ranges only.
 Use -ranges for source without ranges.
 
-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
 
 Inspect Deps
 
 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
@@ -602,7 +565,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:
@@ -626,8 +589,8 @@ 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.
 
 Inspect Tree
 
@@ -681,22 +644,32 @@ duplicates scope=@svc detail=loc pathExclude=[src/generated,"**/* copy.ts"] limi
 
 Mutation
 
-Mutation commands change code through TS/IDE refactors.
-Successful mutations update affected references and imports.
-
+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 move/modulePlan imports do not match the repo style, run:
+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.
-
-Do not read all changed files just because a mutation touched them.
-That defeats the purpose of using AIB for mechanical refactors.
-
-If the command succeeds, the requested mechanical change was applied.
+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.
+
+Choose the mutation by intent:
+rename - rename TypeScript symbols
+move toFile - move TypeScript declarations into one file
+modulePlan - split one source file into several modules
+file move toDir - move whole files into directories
+file rename - rename whole files.
+
+Do not read all changed files just because a mutation touched them.
+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.
 
 When running mutation commands, set the harness timeout to 3 minutes.
@@ -709,7 +682,7 @@ preview  inspect planned edits, then apply by id
 apply    write a previewed change
 execute  write immediately
 
-Use execute for routine rename/move/modulePlan requests.
+Use execute for routine requests.
 
 Use preview/apply when you are learning a mutation command, or when one request contains a large multi-step change that you want to inspect before writing files.
 Typical examples: a huge modulePlan or refactor batch.
@@ -812,42 +785,24 @@ move src/service.types.ts: newType
 This keeps related mutation intent together:
 rename first, then move the renamed symbols.
 
-Imports Normalize
+File Move and File Rename
 
-Use imports normalize for explicit import-style cleanup.
-It rewrites resolved local import/export specifiers inside a chosen file or directory.
-
-Use importNormalize in aib.json for repeated defaults.
+Use file move/rename when the filesystem layout is the intent.
+Do not change filesystem layout manually.
 
-Good for:
-- converting one area to aliases or relative imports
-- cleaning import style after manual edits or broad refactors
-- applying the same import style to a directory without hand-editing files
-- applying new tsconfig aliases after they are added
-
-Controls:
-scope        file/dir scope to normalize
-to           relative|alias|shortestAlias
-preferAlias  select one tsconfig paths pattern when several aliases can resolve the same file
-exclude      files, directories, or glob-like patterns to skip
-all          show all planned edits; avoid on broad directory scopes
+Focused topics:
+aib help file.move file.rename
 
-Run:
-aib imports normalize preview --stdin
-
-Input:
-imports.normalize scope=@svc to=shortestAlias exclude=[@svc/generated,"**/* copy.ts"]
-
-Rewrite imports found inside src/core.
-When an imported file can be expressed through @features/*, prefer that alias.
-
-Input:
-imports.normalize scope=src/core to=alias preferAlias=@features/*
-
-With matching importNormalize config for this scope or a parent scope, use inline CLI commands:
-
-imports normalize preview @svc
-imports normalize execute @svc
+Layout smell trigger:
+If a directory has many related files sharing a prefix, mixed responsibilities, or files that should be grouped by feature, read:
+aib help recipe.file-layout
+
+Imports Normalize
+
+Use imports normalize for explicit import-style cleanup.
+
+Focused topic:
+aib help imports.normalize
 
 JS/TS compatibility
 
@@ -906,30 +861,36 @@ For focused text reads, prefer qr over cat/Get-Content/type, especially when ali
 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
+o=N l=N    range; starting line and line count
+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 wins over other window flags.
 
-Run:
-aib qr --stdin
+{{qr.inline.examples}}
 
-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
+aib rg
 
-Inline:
-aib qr @scripts/a.txt -h 80
-aib qr @scripts/b.py -o 300 -l 50
-aib qr @logs/app.log -a
+Run ripgrep through AIB.
+
+Regular rg:
+  rg <args>
+
+AIB rg:
+  aib rg -- <args>
+
+Everything after `--` is passed as normal ripgrep arguments.
+Use the same args you would pass to `rg`.
+Use normal paths in input. Do not use AIB path aliases here.
+
+Examples:
+  rg -n "TODO" src/core
+  aib rg -- -n "TODO" src/core
 
-Use stdin for several reads.
+  rg -n --column "SomeValue" ws/commands ws/config
+  aib rg -- -n --column "SomeValue" ws/commands ws/config
 
 Need to see TypeScript configs in the repo:
 aib reveal tsconfigs

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

@@ -0,0 +1,44 @@
+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
+  aib config aliases
+
+Help conventions:
+  help-format
+
+Refresh workflow model:
+  basics patterns
+
+Core focused topics:
+  session
+  prefs
+  selectors
+  dsl
+  inspect
+  mutation
+
+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
+  modulePlan
+  refactor.batch
+  imports.normalize
+  view
+  qr
+  rg
+  reveal

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

@@ -0,0 +1,2 @@
+Inline:
+aib qr @scripts/a.txt h=80 @scripts/b.py o=300 l=50 @logs/app.log 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/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/file.move.md

@@ -0,0 +1,44 @@
+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.
+
+file move 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.
+
+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
+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 `..`.
+- file move supports files, not directories.

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

@@ -0,0 +1,33 @@
+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.
+
+file rename renames whole files.
+
+Rename files:
+file rename preview --stdin
+file rename execute --stdin
+file rename apply <previewId>
+
+Use preview/apply when you want to inspect planned file renames before writing files.
+Use execute when you want to write immediately.
+
+Run:
+aib file rename execute --stdin
+
+Input:
+@base src
+rename svc/ws-cli.ts->cli.ts svc/ws-command.ts->command.ts
+rename svc/core/opt-build.ts->builder.ts
+
+How this resolves:
+- source files resolve from @base;
+- target names without a directory stay beside each source file.
+
+Rules:
+- @base sets the base directory for source files.
+- source file paths resolve from @base; cwd-relative paths are accepted when the @base path does not exist.
+- target names without a directory stay beside each source file.
+- target paths with a directory resolve from @base.
+- source paths and target paths may use `..`.
+- file rename supports files, not directories.

package/dist/help/dsl/topics/help-format.md

@@ -1,10 +1,7 @@
 Inline commands below omit the aib prefix.
 Run them as: aib <command>
 
-Stdin examples show command and input separately to avoid shell-specific syntax.
-Stdin Run lines include the aib prefix to avoid confusion.
-
-PowerShell stdin shape:
-@'
-<input>
-'@ | aib <command> --stdin
+Stdin examples show command and input separately to avoid shell-specific syntax.
+Stdin Run lines include the aib prefix to avoid confusion.
+
+{{stdin.examples}}

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

@@ -2,7 +2,7 @@ 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
+- 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
 
@@ -19,9 +19,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

@@ -3,8 +3,9 @@ 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
+- 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.