@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/help/json/docs/modulePlan.md

@@ -1,73 +0,0 @@
-# Module Plan
-
-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.
-
-If imports created by modulePlan do not match the repo style, run:
-aib help config-setup.import-rules
-
-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.
-Use --from with captured input handles when rerunning edited large plans.
-
-Split one large source file into several targets:
-Run:
-aib modulePlan execute --stdin
-
-Input:
-{
-  "sourceFile": "src/large-service.ts",
-  "expectEmpty": true,
-  "modules": [
-    {
-      "target": "src/large-service.types.ts",
-      "entities": ["ServiceOptions", "ServiceMode"]
-    },
-    {
-      "target": "src/large-service.core.ts",
-      "entities": ["LargeService", "createLargeService"]
-    }
-  ]
-}
-
-modulePlan is better than many separate move requests when one large source file should be split into several target files.
-
-Preferred JSON fields:
-sourceFile  file being split
-modules     target groups
-target      output file for one group
-entities    symbols moved into that target
-
-Target files are created when needed.
-The order in the request describes intent; rely on TS/IDE refactors for reference and import updates.
-
-If a large or partial modulePlan request fails, edit the captured input file and rerun with --from.
-For small one-off modulePlan requests, write a corrected request instead.
-
-Latest modulePlan input:
-<session-dir>/inputs/modulePlan/_last.json
-
-Handle:
-aib:input:modulePlan:last
-
-Example:
-modulePlan preview --from aib:input:modulePlan:last

package/dist/help/json/docs/move.md

@@ -1,56 +0,0 @@
-# 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.
-
-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.
-
-If imports created by move do not match the repo style, run:
-aib help config-setup.import-rules
-
-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.
-Use --from with captured input handles when rerunning edited large requests.
-
-Move several entities into one target:
-Run:
-aib move toFile execute --stdin
-
-Input:
-{
-  "sourceFile": "src/service.ts",
-  "targetFile": "src/service.helpers.ts",
-  "entities": ["oldHelper", "OtherHelper"]
-}
-
-Move creates the target file when needed.
-The target can already exist.
-
-The request means:
-take entities from sourceFile and move them into targetFile.
-
-Use refactor batch when the same workflow needs both rename and move steps.
-
-If a large move request fails, edit the captured input file and rerun with --from.
-For small one-off move requests, write a corrected request instead.
-
-Latest move input:
-<session-dir>/inputs/move/_last.json
-
-Handle:
-aib:input:move:last
-
-Example:
-move toFile preview --from aib:input:move:last

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

@@ -1,65 +0,0 @@
-# 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.
-
-If move/modulePlan 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.
-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 and the captured input.
-For large or partial requests, edit the captured input and rerun the remaining or changed intent.
-For small requests, write a corrected request instead.
-
-Prefer batch JSON for related mutations.
-One request can describe several related changes.
-aib captures JSON input automatically so large failed or partial requests can be edited and rerun.
-
-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.
-
-If a large or partial mutation request fails, edit the captured input file and rerun with --from.
-For small one-off requests, write a corrected request instead.
-
-Latest mutation inputs:
-<session-dir>/inputs/rename/_last.json
-<session-dir>/inputs/move/_last.json
-<session-dir>/inputs/refactor/_last.json
-<session-dir>/inputs/modulePlan/_last.json
-
-Example:
-rename preview --from aib:input:rename:last

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

@@ -1,76 +0,0 @@
-# Working Patterns
-
-To refresh help protocol:
-aib help help-protocol
-
-Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
-Use qr for cross-OS quick reads of text files, logs, JSON, scripts, and line windows.
-It is not a replacement for inspect.
-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.
-
-Config excludes can hide files from tree/graph/sync output.
-
-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.
-
-Important: 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/json/docs/prefs.md

@@ -1,40 +0,0 @@
-# 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/json/docs/qr.md

@@ -1,37 +0,0 @@
-# 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 inspect.
-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
--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/json/docs/quick-map.md

@@ -1,30 +0,0 @@
-# Quick Map
-
-Read:
-  qr              quick reads: ts, js, cmd, sh, json, log, txt, etc.
-  view            hidden/truncated output
-
-Inspect:
-  file
-  imports
-  exports
-  members
-  code
-  deps
-  usages
-  graph
-  tree
-  duplicates
-  cycles
-
-Mutate:
-  rename
-  move
-  modulePlan
-  refactor batch
-  imports normalize
-
-Other:
-  config
-  prefs
-  reveal         tsconfig and tsconfig alias discovery

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

@@ -1,72 +0,0 @@
-# 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.
-Use --from with captured input handles when rerunning edited large batches.
-
-Example: rename and move in one request
-
-Run:
-aib refactor batch execute --stdin
-
-Input:
-{
-  "sourceFile": "src/service.ts",
-  "requests": [
-    {
-      "op": "rename",
-      "renames": {
-        "oldHelper": "newHelper",
-        "oldType": "newType"
-      }
-    },
-    {
-      "op": "move",
-      "targetFile": "src/service.helpers.ts",
-      "entities": ["newHelper"]
-    },
-    {
-      "op": "move",
-      "targetFile": "src/service.types.ts",
-      "entities": ["newType"]
-    }
-  ]
-}
-
-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.
-
-If a large or partial refactor batch fails, edit the captured input file and rerun with --from.
-For small one-off refactor requests, write a corrected request instead.
-
-Latest refactor input:
-<session-dir>/inputs/refactor/_last.json
-
-Handle:
-aib:input:refactor:last
-
-Example:
-refactor batch execute --from aib:input:refactor:last

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

@@ -1,47 +0,0 @@
-# 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",
-  "renames": {
-    "oldName": "newName",
-    "OldService": "NewService"
-  }
-}
-
-Rename can use plain names or selectors.
-For methods and properties, prefer JSON so you can pass parent when needed.
-
-If a large rename request fails, edit the captured input file and rerun with --from.
-For small one-off rename requests, write a corrected request instead.
-
-Latest rename input:
-<session-dir>/inputs/rename/_last.json
-
-Handle:
-aib:input:rename:last
-
-Example:
-rename preview --from aib:input:rename:last

package/dist/help/json/docs/reveal.md

@@ -1,30 +0,0 @@
-# Reveal
-
-Use reveal to inspect TypeScript config discovery used by AIB.
-
-Reveal is for config/setup diagnosis.
-Use it when aliases, sync, imports normalize, or tsconfig excludes depend on which tsconfig files AIB sees.
-
-Commands:
-aib reveal tsconfigs
-aib reveal tsaliases
-
-tsconfigs shows visible TypeScript configs and config-excluded configs.
-tsaliases shows baseUrl, paths, extends, inherited paths, duplicated inherited paths, and overridden inherited paths.
-
-Controls:
-all    show all output instead of compact output
-nec    no config excludes; ignore sync.tsconfig.exclude
-ned    no default excludes
-limit  max visible groups/items before + N more
-
-Examples:
-aib reveal tsconfigs
-aib reveal tsconfigs +all
-aib reveal tsconfigs +nec limit=20
-aib reveal tsaliases
-aib reveal tsaliases +all
-aib reveal tsaliases +nec
-
-Use tsconfigs before tuning sync.tsconfig.exclude.
-Use tsaliases before creating AIB pathAliases or configuring import normalization.

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

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

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

@@ -1,77 +0,0 @@
-# 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 captured inputs, saved outputs, 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 inputs/outputs, 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
-
-Every JSON stdin/from request is captured.
-
-Latest input per kind:
-<session-dir>/inputs/<kind>/_last.json
-
-Handle:
-aib:input:<kind>:last
-
-Use --from when editing the captured input costs less than rebuilding the request.
-For small one-off requests, write a corrected request instead.
-Do not read input handles into context unless you specifically need to inspect the payload.
-
-Examples:
-rename preview --from aib:input:rename:last
-refactor batch <command> --from aib:input:refactor: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/json/docs/view.md

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