@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/help/bootstrap.bash.md

@@ -0,0 +1,742 @@
+AIB
+
+aib is a local CLI for TS/JS code work backed by IDE and TypeScript APIs.
+It can inspect symbols, usages, dependencies, duplicates, focused code, and run IDE-backed mutations.
+
+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 clear
+
+Run:
+aib session clear
+
+Stdin examples show command and input separately to avoid shell-specific syntax.
+Stdin Run lines include the aib prefix to avoid confusion.
+
+Bash/Zsh:
+aib <command> --stdin <<'EOF'
+<input>
+EOF
+
+aib inspect --stdin <<'EOF'
+tree . +onlyDirs limit=20
+EOF
+
+Basics
+
+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 TypeScript semantic 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.
+
+Working patterns
+
+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.
+
+Set the command timeout to 5 minutes for AIB requests.
+
+If a mutation command times out or returns no final output, use:
+
+aib execution status last
+
+This is an escape hatch for recovering the latest mutation status/result.
+
+After reading bootstrap for the first time in a repo, run:
+
+aib config; aib help help-protocol recipes rules
+
+Use the output as the repo-local AIB map:
+- pathAliases show short paths to use in AIB requests;
+- importRules show how move/modulePlan should create imports;
+- importNormalize shows defaults for explicit imports normalize;
+- excludes show which noise is intentionally hidden from tree/graph/sync.
+
+If pathAliases are missing, stale, or weak for repeated paths, run:
+aib help config-setup.aliases
+
+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 imports.normalize
+
+If tree/graph output includes known repo noise, run:
+aib help config-setup.excludes
+
+If sync or reveal shows too many visible TypeScript configs, run:
+aib help config-setup.tsconfigs
+
+Example aib.json config:
+
+{
+  "pathAliases": {
+    "svc": "src/services",
+    "cli": "packages/cli/src"
+  },
+  "importRules": [
+    {
+      "scope": ".",
+      "specifier": "shortest",
+      "ending": "auto",
+      "builtin": "bare",
+      "unusedImports": "remove"
+    }
+  ],
+  "importNormalize": [
+    {
+      "scope": "src",
+      "to": "shortestAlias",
+      "exclude": ["src/generated"]
+    }
+  ],
+  "inspect.graph.exclude": [
+    "**/* copy.ts"
+  ]
+}
+
+pathAliases define short request aliases for paths agents repeat in aib commands.
+Use them to reduce input tokens for repeated inspect and mutation work.
+
+Aliases are for aib request paths. They do not change TypeScript imports by themselves.
+For import style after mutations, use importRules.
+
+importRules control imports created or expanded by move/modulePlan mutation cleanup.
+They do not rewrite the whole project.
+
+A non-empty importRules block in aib.json is the complete AIB import-style authority.
+Omitted fields keep TypeScript/AIB defaults; they are not filled from editor settings.
+When importRules is empty, AIB may reuse explicit workspace-local IDE/TS preferences.
+
+Do not assume IDE/TS defaults match the repo style.
+Set importRules before large move/modulePlan work so imports do not need manual cleanup.
+
+importNormalize defines default rules for explicit aib imports normalize commands.
+
+It does not run automatically during move/modulePlan; use importRules for mutation-time cleanup.
+
+AIB has four config exclude fields:
+inspect.graph.exclude
+inspect.tree.files.exclude
+inspect.tree.onlyDirs.exclude
+sync.tsconfig.exclude
+
+For all of them, node_modules, .git, dist, build, out, and .tmp are skipped by default.
+
+Use config excludes for generated files, backups, local copies, nested workspaces, seed projects, or other repository-specific noise.
+
+Graph excludes affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, and saved graph files.
+Tree excludes affect directory/file discovery output.
+AIB syncs and watches visible tsconfigs.
+sync.tsconfig.exclude affects which TypeScript configs AIB syncs and watches.
+
+Session
+
+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 and aliases.
+
+Prefer short session names:
+aa, tr, qa, a2
+
+Create:
+session init --name <name>
+
+Follow the command output.
+If aib says multiple sessions exist, use the session you created explicitly:
+aib -s <name> <command>
+
+Or bind this shell:
+AIB=<name>
+
+If you want to prune session data, use:
+session clear
+
+After clear, keep using the same session.
+
+Check:
+session status
+
+Reusable index handles look like:
+`aib:graph:<name>`  `aib:usages:<name>`
+
+Pass index handles back to the matching inspect command with `--from-file` or `from` in DSL.
+
+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.
+
+Example:
+type WsOptions
+class WsOptions
+
+If aib needs the exact entity, use:
+t-WsOptions
+c-WsOptions
+
+Selectors list:
+f-name  function
+c-Name  class
+i-Name  interface
+t-Name  type
+v-name  variable
+e-Name  enum
+ns-Name namespace
+m-name  method, usually with parent
+p-name  property, usually with parent
+
+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
+@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
+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
+
+Inspect
+
+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
+path alias candidates            aliasCandidates
+repeated declarations/helpers    duplicates
+local import cycles              cycles
+
+Cycles are available but not expanded in bootstrap:
+aib help inspect.cycles
+
+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,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
+
+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.
+
+Inspect File
+
+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 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
+
+Run:
+aib inspect --stdin
+
+Input:
+file @svc/service.ts
+file src/index.ts
+
+Inspect Imports
+
+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
+
+Inspect Exports
+
+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]
+
+Inspect Members
+
+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
+
+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]
+
+Inspect Code
+
+Use code when you know file path and declaration/member selector, but do not know ranges.
+
+Run:
+aib inspect --stdin
+
+Input:
+code @svc/service.ts Service.{render,reset} normalize
+code @svc/serviceB.ts ServiceB.{constructor} default
+
+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
+- 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 Usages
+
+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
+
+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 Graph
+
+Graph is a strong tool for file/module connectivity.
+Use it when the question is about boundaries, ownership, hubs, entrypoints, or how files relate through imports.
+Do not use graph for one symbol; use deps/usages instead.
+
+Focused topic:
+aib help inspect.graph
+
+Inspect Tree
+
+Use tree to list a compact directory layout.
+It is useful before focused inspect when you know the area but not the exact file.
+
+Controls:
+scope, depth, minDepth, limit, only, exclude, onlyDirs, ned, nec
+
+Specific:
+depth     max nesting depth; depth=N
+minDepth  hide shallower paths; minDepth=N
+onlyDirs  show directories only; +onlyDirs
+only      keep only matching files/dirs; only=[...]
+exclude   skip matching files/dirs; exclude=[...]
+ned       no-default-exclude; show paths hidden by built-in excludes; +ned
+nec       no-config-exclude; ignore inspect.tree.*.exclude from aib.json; +nec
+
+Run:
+aib inspect --stdin
+
+Input:
+tree src depth=4 +onlyDirs limit=200 +ned +nec
+tree @svc depth=3 only=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
+tree src depth=3 only=["src/services/**"] limit=80
+
+Inspect Duplicates
+
+Use duplicates to find repeated top-level names and exact declaration copies.
+
+Focused topic:
+aib help inspect.duplicates
+
+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.
+
+Rename
+
+Rename is for semantic symbol renames.
+It follows TypeScript references.
+It is not plain-text replacement.
+
+Run:
+aib mutate execute --stdin
+
+Input:
+@source src/service.ts
+rename oldName->newName OldService->NewService
+
+Move
+
+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
+
+Run:
+aib mutate execute --stdin
+
+Input:
+@source src/service.ts
+move src/service.helpers.ts: oldHelper OtherHelper
+move src/service.types.ts: ServiceOptions
+
+Module Plan
+
+Use module only for a full-file split: moving all declarations from one source file into target modules.
+
+Focused topic:
+aib help modulePlan
+
+Mixed Mutation
+
+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
+
+File Layout
+
+Use moveToDir and renameFile when the filesystem layout is the intent.
+Do not change filesystem layout manually.
+
+Focused topics:
+aib help moveToDir renameFile
+
+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
+
+Import Boundaries
+
+When you create a barrel/index file and want consumers to import through it,
+or when consumers import through a barrel but should use direct source imports, read:
+
+aib help recipe.import-boundary
+
+JS/TS compatibility
+
+With tsconfig:
+TS/TSX              inspect + mutate rename/move/module
+JS/MJS/JSX ESM      inspect + mutate rename/move/module
+CJS / JS CommonJS   inspect + mutate rename
+
+Without tsconfig:
+JS/MJS/JSX/CJS      inspect only
+mutate rename/move/module require tsconfig
+
+CommonJS means .cjs or module.exports / exports.*.
+
+View Hidden Output
+
+AIB keeps large outputs compact.
+When part of a result is hidden, output may include:
+
+view: aib:res_<id>
+
+Use view to fetch the hidden part without repeating what you already saw.
+
+When a batch has several hidden results of the same kind, output may include:
+
+view all code: aib:res_<id>
+view all members: aib:res_<id>
+
+A `view all` handle covers hidden parts from all results of that kind.
+
+For code views, narrow what you fetch:
+only    show only these hidden code entities
+except  show all hidden code except these entities
+
+Run:
+aib view --stdin
+
+Input:
+view aib:res_<id_1> only=[ClassA.{bigA,bigB},bigQ,ClassB.bigB]
+view aib:res_<id_2> except=[ClassC.bigC]
+
+Inline:
+aib view aib:res_<id_1> --only bigQ --only "ClassA.{bigA,bigB}"
+aib view aib:res_<id_2> --except ClassB.bigB --except ClassC.bigC
+
+Quick Read
+
+Use qr for cross-OS quick reads of text files: ts, js, cmd, sh, json, log, txt, ndjson, etc.
+Use it for compact line windows and batching.
+qr supports AIB path aliases.
+
+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
+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 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.
+
+Use s= when copying ranges from inspect file.
+Combine windows for the same file instead of repeating the path.
+
+Inline:
+aib qr @svc/users.ts s=3:42,66:84,92 @scripts/a.txt h=80 @scripts/b.py r=300:50,500 .prettierrc all
+
+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
+
+Need to see TypeScript configs in the repo:
+aib reveal tsconfigs
+
+Need to see TypeScript aliases across the repo:
+aib reveal tsaliases