@automaton-labs/aib 0.0.6 → 0.0.7

package/dist/help/dsl/docs/dsl.md

@@ -10,9 +10,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/docs/file.move.md

@@ -0,0 +1,46 @@
+# File 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.
+
+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/docs/file.rename.md

@@ -0,0 +1,35 @@
+# File 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.
+
+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/docs/inspect.code.md

@@ -4,7 +4,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
 
@@ -21,9 +21,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/docs/inspect.deps.md

@@ -3,18 +3,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/docs/inspect.file.md

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

package/dist/help/dsl/docs/inspect.graph.md

@@ -37,7 +37,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:
@@ -61,8 +61,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.
 
 Specialized graph command:
 Run:

package/dist/help/dsl/docs/inspect.md

@@ -28,16 +28,16 @@ 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/docs/mutation.md

@@ -1,21 +1,31 @@
 # 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.
@@ -28,7 +38,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.

package/dist/help/dsl/docs/patterns.md

@@ -10,7 +10,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.
@@ -20,10 +20,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.
-
 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

package/dist/help/dsl/docs/qr.md

@@ -11,27 +11,12 @@ 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
-
-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/docs/quick-map.md

@@ -2,6 +2,7 @@
 
 Read:
   qr              quick reads: ts, js, cmd, sh, json, log, txt, etc.
+  rg              use `aib rg -- <args>` instead of `rg <args>`
   view            hidden/truncated output
 
 Inspect:

package/dist/help/dsl/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 file.move file.rename
+
+If you only need to move files, do not read file.rename.
+If you only need to rename files, do not read file.move.
+
+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/docs/rg.md

@@ -0,0 +1,22 @@
+# RG
+
+aib rg
+
+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
+
+  rg -n --column "SomeValue" ws/commands ws/config
+  aib rg -- -n --column "SomeValue" ws/commands ws/config

package/dist/help/dsl/docs/selectors.md

@@ -18,6 +18,7 @@ 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

package/dist/help/dsl/docs/session.md

@@ -4,7 +4,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