@automaton-labs/aib 0.0.1

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

@@ -0,0 +1,14 @@
+Recommended:
+For TS/JS code work, use aib. Start with {{docsPath}}.
+
+Strict:
+For TS/JS code work in this repo, prefer aib before broad file reads. Start with {{docsPath}}.
+
+Minimal:
+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}}.

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

@@ -0,0 +1,12 @@
+Use the active session while you work.
+
+Examples are patterns, not limits.
+Feature sections show common high-value uses, not every valid use.
+Adapt requests to the task: combine features, batch related questions, and skip steps when you already have enough context.
+
+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.
+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/dsl.md

@@ -0,0 +1,23 @@
+DSL request model:
+- directives set defaults for following requests
+- each request line can override defaults with key=value
+- +flag means true
+- -flag means false
+- file/imports/exports/members/code/deps accept a path as the first positional argument; examples below use this shape.
+- Use @file when several following operations share the same file.
+- 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
++flag                      boolean true
+-flag                      boolean false
+>name                      save reusable artifact when supported
+old->new                   rename pair
+Parent.member              parent-qualified member
+Parent.{a,b}               several members under one parent
+key=[a,b]                  list value for repeatable fields
+file="path with spaces.ts" quote values with spaces
+detail=sum|loc|code        aliases for summary|locations|code
+from=...                   alias for fromFile

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

@@ -0,0 +1,10 @@
+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

package/dist/help/dsl/topics/imports.normalize.md

@@ -0,0 +1,34 @@
+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.
+
+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
+
+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

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

@@ -0,0 +1,27 @@
+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
+
+Controls:
+file, entity, entities, parent, show, ranges
+
+Specific:
+show  include source output
+
+Defaults: +show +ranges
+Use -show for names/ranges only.
+Use -ranges for source without ranges.
+
+Prefs:
+inspect.code.maxNonEmptyLines
+
+Run:
+aib inspect --stdin
+
+Input:
+code @svc/service.ts Service.{render,reset} normalize
+code @svc/serviceB.ts ServiceB.{constructor}

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

@@ -0,0 +1,30 @@
+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
+- debugging mutation failures caused by local dependency shape
+
+Controls:
+file, entity, entities, parent
+
+Run:
+aib inspect --stdin
+
+Input:
+deps @svc/service.ts entities=[createService,normalize,Service.{render,reset}]
+deps @svc/serviceB.ts ServiceB.{constructor} getConfig
+
+inspect deps src/service.ts Service
+
+Batch several symbols when you are planning a move:
+Run:
+aib inspect --stdin
+
+Input:
+@file src/service.ts
+deps Service
+deps ServiceOptions
+deps createService

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

@@ -0,0 +1,43 @@
+Use duplicates to find repeated top-level names and exact declaration copies.
+It is useful when many files may contain copied local helpers, duplicated types, or repeated declarations.
+
+Start with summary for broad scopes.
+Use locations when you need files/lines.
+Use code only for duplicate names you are ready to inspect.
+
+Controls:
+scope, detail, limit, offset, kinds, entities, exclude, pathExclude
+
+Specific:
+entities    only these duplicate names/selectors
+exclude     skip these names/selectors
+pathExclude skip files or path/glob-like patterns
+kinds       selector kinds, e.g. f, t, c, etc.; kinds=[...]
+
+Summary scan:
+Run:
+aib inspect --stdin
+
+Input:
+duplicates scope=src detail=sum limit=20
+
+Skip noisy duplicate names:
+Run:
+aib inspect --stdin
+
+Input:
+duplicates scope=src detail=sum exclude=[Props,Options] limit=20
+
+Skip files by path/glob-like pattern:
+Run:
+aib inspect --stdin
+
+Input:
+duplicates scope=src detail=loc pathExclude=[src/generated,"**/* copy.ts"] limit=20
+
+Inspect specific duplicate code:
+Run:
+aib inspect --stdin
+
+Input:
+duplicates scope=src detail=code getBoolean WsOptions

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

@@ -0,0 +1,32 @@
+Use exports to see the public API of one file.
+It answers what other files can import from that file.
+
+Important:
+inspect.file marks exported declarations already.
+
+Do not batch this for a plain implementation file:
+file src/service.ts
+exports src/service.ts
+
+Use exports when you need public module surface, barrels, re-exports, export *, or resolveStar.
+
+Good for:
+- checking a module boundary or public surface
+- understanding facade/barrel files
+- resolving export * when the local file only re-exports from elsewhere
+- comparing API shape when public imports matter
+
+Controls:
+file, ranges, resolveStar
+
+Specific:
+resolveStar  resolve export * through re-exported modules; +resolveStar
+
+Run:
+aib inspect --stdin
+
+Input:
+exports src/service.ts +ranges
+exports src/index.ts +resolveStar
+
+inspect exports src/service.ts [--ranges] [--resolve-star]

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

@@ -0,0 +1,30 @@
+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
+- 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
+Use -ranges to show names without ranges.
+
+Run:
+aib inspect --stdin
+
+Input:
+file @svc/service.ts +localOnly
+file src/index.ts
+
+inspect file src/service.ts [--ranges] [--local-only]

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

@@ -0,0 +1,110 @@
+Use graph when the question is about file/module boundaries, not one symbol.
+It builds a reusable map of local import relationships, then lets you focus files inside that map.
+
+Good for:
+- mapping an unfamiliar directory or subsystem
+- seeing which files are hubs, entrypoints, or leaves
+- comparing a few known areas without mapping all src
+- choosing files/entities to inspect next
+- checking module boundaries when ownership is unclear
+
+Use deps for one entity's outgoing dependencies.
+Use usages for real incoming references.
+Use graph for file-level connectivity.
+
+Model:
+build graph: scope + view + save
+query graph: from + focus + output toggles
+
+view controls what enters the saved graph.
+focus only expands details for files already inside it.
+If focus misses a file, rebuild with wider scope or view.
+
+Default view:
+directory scope -> local
+file or multiple scopes -> neighbors
+from -> uses the saved graph
+
+Views:
+local      only files inside scope; best directory map
+neighbors  direct import neighborhood; best file-centered map
+expanded   wider neighborhood; more output
+
+Scope choice:
+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.
+Graph can be noisy; shape it for the current task.
+
+Controls:
+scope, view, from, focus, symbolUsage, edges, hubs, entrypoints, leaves, exclude, save
+
+Specific:
+view         local|neighbors|expanded
+from         reuse saved graph index; from=aib:graph:<name>
+focus        focus a file inside the graph; focus=path
+symbolUsage  show imported symbols on edges; +symbolUsage
+
+edges/hubs/entrypoints/leaves  output section toggles; +name or -name
+
+Run:
+aib inspect --stdin
+
+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 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.
+
+Specialized graph command:
+Run:
+aib inspect graph --stdin
+
+Input:
+graph scope=@svc view=local >services-graph
+graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbolUsage -edges
+
+Multiple scopes:
+Run:
+aib inspect --stdin
+
+Input:
+graph scope=[src/main/server,src/services/ws] view=local >server-ws-graph
+
+scope accepts one file/dir or an array.
+
+Skip noisy files:
+Run:
+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
+focus         selected files with imports/importedBy
+hubs          highly connected files
+entrypoints   scoped files imported by nobody in graph
+leaves        scoped files importing nobody in graph
+edges         local file-to-file imports
+saved         reusable aib:graph handle

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

@@ -0,0 +1,13 @@
+Use imports to inspect static and dynamic imports in a file.
+If there are no dynamic imports, the dynamic imports block is omitted.
+
+Controls:
+file, ranges
+
+Defaults: +ranges
+
+Run:
+aib inspect --stdin
+
+Input:
+imports @svc/service.ts

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

@@ -0,0 +1,69 @@
+Inspect helps you turn an unknown code area into a small working model.
+
+Use it to understand what exists, how pieces connect, what repeats, where a change can spread, and which exact code should enter context next.
+
+One useful flow:
+map -> focus -> code
+
+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
+
+Prefer one batch DSL request for related questions.
+
+Batch example:
+
+Run:
+aib inspect --stdin
+
+Input:
+@file @svc/service.ts
+file
+file @svc/serviceB.ts
+members Service
+code entities=[Service.{render,reset},normalize]
+code @svc/serviceC.ts ServiceC -ranges
+usages target=@svc/service.ts normalize scope=src detail=loc
+duplicates scope=src/scripts detail=sum limit=20
+
+How inheritance works above:
+@file sets the default file for following file-like inspect requests.
+file uses @svc/service.ts.
+file @svc/serviceB.ts overrides the default for that one request.
+members Service uses @svc/service.ts because it has no file override.
+code entities=[...] also uses @svc/service.ts.
+code @svc/serviceC.ts ServiceC overrides the file and disables ranges for that request.
+usages sets its own target/scope/detail because it searches references instead of reading the default file.
+duplicates sets its own scope because it scans a directory.
+
+Inspect request fields:
+
+file      source file; first positional path, @file path, or file=path
+target    file or directory to analyze; target=path
+scope     where to search; scope=path or scope=[a,b]
+entity    one symbol selector; entity=name or positional selector
+entities  several symbol selectors; entities=[...] or positional selectors
+parent    parent class/interface for methods/properties; Parent.member or parent=Name
+ranges    include line/range metadata
+exclude   skip paths or names depending on operation; exclude=[...]
+detail    output level; detail=sum|loc|code
+all       return all items; +all
+limit     max items in one page; limit=N
+offset    page offset; offset=N
+save      save reusable artifact where supported; >name
+
+Operation sections list their supported controls.
+Specific explains controls whose meaning is local to that operation.

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

@@ -0,0 +1,22 @@
+Use members to map a class/interface/object-like symbol without reading its body.
+It shows the internal shape of a parent entity without reading its full body.
+
+Good for:
+- listing member names when the parent entity is known
+- narrowing a large parent entity to relevant members
+- understanding object shape before changing or moving related code
+
+Controls:
+file, entity, entities, ranges, limit, offset, all
+
+Prefs:
+inspect.members.maxItems
+inspect.members.all
+
+Run:
+aib inspect --stdin
+
+Input:
+members @svc/service.ts entities=[Service,ServiceOptions] +all +ranges
+
+inspect members src/service.ts Service [--limit N] [--offset N] [--all] [--ranges]

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

@@ -0,0 +1,20 @@
+Use tree to list a compact directory layout.
+It is useful before focused inspect when you know the area but not the exact file.
+
+node_modules, .git, dist, build, out, and .tmp are skipped by default.
+
+Controls:
+scope, depth, minDepth, limit, include, exclude, onlyDirs
+
+Specific:
+depth     max nesting depth; depth=N
+minDepth  hide shallower paths; minDepth=N
+onlyDirs  show directories only; +onlyDirs
+include   only matching files/dirs; include=[...]
+
+Run:
+aib inspect --stdin
+
+Input:
+tree src depth=4 +onlyDirs limit=200
+tree @svc depth=3 include=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]

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

@@ -0,0 +1,46 @@
+Use usages to find who references a file, directory, or entity inside a scope.
+It reports real references, not unused imports or text matches.
+For broad impact checks, target-local usages are hidden automatically when the target is inside a wider scope.
+Use includeTarget only when references inside the target file or directory matter.
+
+Good for:
+- checking impact before changing behavior
+- finding consumers of an entity or module area
+- confirming whether extracted or renamed code still has callers
+- getting caller locations or caller code without broad file scans
+
+Use detail=code directly when you already need caller code.
+Use detail=loc + save when the first question is impact shape and you may expand only part of it later.
+
+Controls:
+target, scope, entity, entities, parent, detail, limit, all, save, includeTarget
+
+Specific:
+includeTarget  include references inside the target file/directory; +includeTarget
+
+Prefs:
+inspect.usages.maxLocations
+inspect.usages.maxCodeBlocks
+
+Run:
+aib inspect --stdin
+
+Input:
+usages target=@svc/service.ts entities=[createService,normalize,Service.{render,reset}] scope=[src/app,src/tests] detail=loc >service-usages
+
+Expand saved usages when needed:
+inspect usages --from-file aib:usages:service-usages --focus createService --detail code --limit 20
+
+inspect usages src/service.ts createService --scope src --detail locations [--limit N] [--all] [--save name]
+
+Expand saved usages by focusing the reusable usages index:
+inspect usages --from-file aib:usages:service-usages --focus createService --detail code
+
+Use the saved usages handle with --from-file/from to focus or expand the reusable index.
+
+Directory target:
+Run:
+aib inspect --stdin
+
+Input:
+usages target=src/shared scope=[src/app,src/renderer] detail=sum >shared-usages

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

@@ -0,0 +1,38 @@
+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.
+
+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.
+
+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.
+
+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.
+Each module line declares one target and the entities that should move there.

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

@@ -0,0 +1,27 @@
+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.
+
+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 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.
+
+Move several entities into one target:
+Run:
+aib move toFile execute --stdin
+
+Input:
+@source src/service.ts
+move src/service.helpers.ts: oldHelper OtherHelper

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

@@ -0,0 +1,45 @@
+Mutation commands change code through TS/IDE refactors.
+Successful mutations update affected references and imports.
+
+After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or checks show a real issue.
+
+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.
+After failure or partial success, use the output to decide the next request.
+
+When running mutation commands, set the harness timeout to 3 minutes.
+If the harness stops waiting before final output appears, recover with:
+
+aib execution status last
+
+Modes:
+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 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.
+
+preview/apply uses more tool calls and more output tokens.
+preview validates input and planned edits, but writing files can still hit a TS/IDE refactor error.
+execute writes immediately and reports what changed.
+
+If a mutation cannot be completed, aib reports the failed part.
+
+Prefer batch DSL for related mutations.
+One request can describe several related changes.
+
+When a batch mutation partly fails, split the next request by failure type.
+
+If the failure is wrong input, fix the selector/entity/file and run the corrected remaining intent.
+If TS/IDE cannot apply one part of the batch, do not treat the whole intent as failed.
+Run the next request without the failed part and let aib report any later failures.
+Then decide whether failed parts need smaller requests or manual fallback.