@automaton-labs/aib 0.0.1

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

@@ -0,0 +1,47 @@
+# Mutation
+
+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.

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

@@ -0,0 +1,178 @@
+# Working Patterns
+
+Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
+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
+
+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.
+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
+code @svc/b.ts ServiceB
+
+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.
+
+For mutation commands, set the shell/tool harness timeout to 3 minutes.
+
+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.
+
+Before repeated mutation work, check aib config:
+
+aib config
+
+Set pathAliases for repeated request paths.
+Set importRules so move/modulePlan create imports in the project style.
+
+This avoids repeating long paths in requests and avoids manual import cleanup after mutations.
+Do this before large move/modulePlan work, not after cleanup becomes repetitive.
+
+Example aib.json config:
+
+{
+  "pathAliases": {
+    "svc": "src/services",
+    "cli": "packages/cli/src",
+    "ext": "packages/extension/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.
+
+AIB starts from IDE/TS import preferences.
+For mutation cleanup, matching importRules in aib.json take priority.
+
+Do not assume IDE/TS defaults match the repo style.
+Set importRules before large move/modulePlan work so imports do not need manual cleanup.
+
+Fields:
+scope      repo-relative file or directory scope; most specific scope wins
+specifier  relative|shortest|project-relative|non-relative
+ending     auto|minimal|index|js
+builtin    node|bare
+unusedImports  remove|preserve
+
+Defaults:
+specifier omitted      IDE/TS decides
+ending omitted         IDE/TS decides
+builtin omitted        keep TS/project builtin style
+unusedImports omitted  keep unused imports
+
+specifier:
+relative          best for local relative imports
+shortest          best for shortest valid alias/path output
+project-relative  best for root-relative project imports
+non-relative      best for package or alias imports
+
+ending:
+minimal  best for extensionless TS imports
+js       best for ESM-style TS projects that require .js
+auto     leaves the decision to TypeScript
+index    best for explicit index import style
+
+builtin:
+node        path -> node:path; best for explicit Node builtin imports
+bare        node:path -> path; best for bare Node builtin imports
+omit field  keeps TypeScript/project output; add builtin if agents keep fixing this manually
+
+unusedImports:
+remove    clean unused imports in mutation-touched files
+preserve  keep unused imports
+omit      same as preserve
+
+Mutation-touched files are files where TS produced edits: source/target files and any reference/update files TS changed.
+Recommended value: remove
+
+importNormalize defines reusable defaults for aib imports normalize.
+Use it when the same normalize request would otherwise be repeated.
+
+It affects explicit import normalize commands only.
+It does not run automatically during move/modulePlan; use importRules for mutation-time cleanup.
+
+Fields:
+scope        repo-relative file or directory scope; most specific scope wins
+to           relative|alias|shortestAlias
+preferAlias  tsconfig paths pattern used when to=alias
+exclude      files, directories, or glob-like patterns to skip
+
+to:
+relative       rewrite resolved local imports to relative paths
+alias          rewrite resolved local imports to a matching tsconfig alias
+shortestAlias  rewrite to the shortest valid alias specifier
+
+preferAlias:
+@shared/*      prefer one alias pattern when several aliases can resolve the same file
+
+inspect.graph.exclude skips files before graph builds the model.
+Use it for generated files, backups, local copies, or other paths that make graph output noisy.
+
+Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+
+Leave feedback while working.
+
+aib is built for agents. Agent feedback is the main signal for improving output, docs, mutations, and token efficiency.
+
+Use feedback when something is wrong, unclear, noisy, or could be more efficient.
+
+Format:
+feedback "kind | message"
+feedback "kind | topic | message"
+
+Kinds:
+bug, confusion, friction, idea, other
+
+Topic is optional. Choose any short topic that helps classify the feedback.
+
+Example:
+feedback "friction | imports | normalize required manual cleanup"

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

@@ -0,0 +1,40 @@
+# 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.symbols boolean
+inspect.graph.symbolUsage boolean
+
+Use prefs to reduce repeated request fields and avoid unnecessary output.
+
+If graph output is too noisy:
+session prefs set inspect.graph.hubs false inspect.graph.leaves false
+
+Change prefs while working. Turn details back on when you need them.

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

@@ -0,0 +1,33 @@
+# Quick Read
+
+Use qr to read arbitrary text files with compact, cross-platform line windows.
+qr supports AIB path aliases.
+
+qr is not a replacement for inspect.
+Use it as a token-efficient way to read text data when semantic inspect is not needed.
+
+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
+
+If no window is provided, qr uses -h 80.
+If -a 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.

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

@@ -0,0 +1,44 @@
+# Refactor Batch
+
+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.
+
+refactor batch runs related mutation requests together.
+Use it when one workflow needs ordered steps, such as rename plus move.
+
+Use modulePlan when the main intent is only to split one large file into target modules.
+Use refactor batch when the split also includes coordinated renames or mixed mutation steps.
+
+refactor batch preview --stdin
+refactor batch execute --stdin
+refactor batch apply --stdin
+
+Use preview/apply when you want to inspect a large mixed plan before writing files.
+Use execute when you want to write immediately.
+
+Example: rename and move in one request
+
+Run:
+aib refactor batch execute --stdin
+
+Input:
+@source src/service.ts
+rename oldHelper->newHelper oldType->newType
+move src/service.helpers.ts: newHelper
+move src/service.types.ts: newType
+
+This keeps related mutation intent together:
+rename first, then move the renamed symbols.
+
+Use top-level sourceFile when requests operate on the same file.
+Override file/sourceFile inside a request when one request targets another file.
+
+Supported request kinds:
+rename
+move
+
+Use separate command help when the workflow only needs one mutation kind.

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

@@ -0,0 +1,39 @@
+# 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.
+
+If a name is ambiguous, use selectors.
+Run help selectors to refresh selector syntax.
+
+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
+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.

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

@@ -0,0 +1,23 @@
+# Selectors
+
+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
+m-name  method, usually with parent
+p-name  property, usually with parent

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

@@ -0,0 +1,61 @@
+# 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, aliases, and prefs.
+
+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
+
+Handles:
+Commands may return handles for hidden output or reusable indexes.
+
+Hidden output:
+aib:res_<id>
+
+Use view to fetch only the hidden part without repeating the original request:
+aib view aib:res_<id>
+
+Reusable indexes:
+aib:usages:<name>
+aib:graph:<name>
+
+Usages and graph handles store computed indexes.
+Use them with --from-file to focus or expand the saved result:
+
+inspect usages --from-file aib:usages:service-usages --focus createService --detail code
+inspect graph --from-file aib:graph:services-graph --focus src/service.ts
+
+Escape hatch for latest mutation status/result:
+aib execution status last
+
+Prefs are stored in the session.
+Use prefs when you want repeated CLI behavior without repeating request fields.
+
+Set several prefs:
+session prefs set inspect.graph.hubs false inspect.graph.leaves false
+
+Show current overrides:
+session prefs get
+
+See help prefs for the full list.

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

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