@automaton-labs/aib 0.0.3 → 0.0.5

package/dist/help/dsl/docs/first-setup.md

@@ -0,0 +1,292 @@
+# First Setup
+
+Use this when the user asks you to set up AIB for a repository.
+
+If you have not loaded the current bootstrap, run:
+aib help bootstrap
+
+1. Detect existing setup
+
+Run:
+
+aib config
+
+If AIB reports that no config exists, continue to initialization.
+
+If config exists:
+- verify that root is the intended repository root;
+- keep existing settings if they are still valid and useful;
+- only add missing project-specific aliases, rules, or excludes;
+- do not regenerate aib.json.
+
+If config resolves from a parent directory, verify that this is intentional.
+Do not continue setup inside a nested worktree or copied project if AIB is using the parent repository config.
+
+2. Initialize if missing
+
+From the repository root, run:
+
+aib init --session-dir .tmp/aib
+
+Use the output to check:
+- root is the intended repository root;
+- config is <root>/aib.json;
+- sessionDir is set;
+- cleanup/deletion/runtime TTLs are shown;
+- not set includes the setup sections that still need decisions.
+
+Do not create sessions yet.
+
+3. Configure repository-specific behavior
+
+Edit aib.json directly.
+
+Keep existing settings if they are still valid and useful.
+Update settings that are stale, noisy, too broad, or no longer match the repository.
+
+Use not set as the checklist for the setup sections below.
+
+4. Configure path aliases
+
+Check TypeScript aliases for hints:
+
+aib reveal tsaliases
+
+Use this to see existing tsconfig paths and baseUrl values.
+They can reveal stable work areas, but they are not a list to copy.
+
+Add pathAliases for long paths that are likely to appear repeatedly in AIB requests.
+Prefer aliases for real work areas, package roots, or deep directories.
+
+A good alias:
+- saves meaningful path tokens;
+- points to a stable work area;
+- is easy to recognize later.
+
+A bad alias:
+- duplicates a short path like "src": "src", "packages": "packages", "scripts": "scripts";
+- points to a rarely used folder;
+- mirrors the directory tree without a workflow reason.
+
+Having 20-30 good aliases is fine for a large repo or monorepo.
+
+Example:
+
+"pathAliases": {
+  "wstore": "apps/web/src/shared/store",
+  "wapi": "apps/web/src/shared/api",
+  "whooks": "apps/web/src/shared/utils/hooks",
+  "pmail": "packages/email/src",
+  "putils": "packages/utils/src",
+  "arules": "docs/agent/rules"
+}
+
+5. Configure import rules
+
+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.
+
+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
+
+If the repository has one import style, use one broad rule:
+
+"importRules": [
+  {
+    "scope": ".",
+    "specifier": "shortest",
+    "ending": "auto",
+    "builtin": "node",
+    "unusedImports": "remove"
+  }
+]
+
+Use scoped rules only when areas differ by style, for example packages use aliases but scripts use relative imports:
+
+"importRules": [
+  {
+    "scope": "packages",
+    "specifier": "shortest",
+    "ending": "auto",
+    "builtin": "node",
+    "unusedImports": "remove"
+  },
+  {
+    "scope": "scripts",
+    "specifier": "relative",
+    "ending": "auto",
+    "builtin": "node",
+    "unusedImports": "remove"
+  }
+]
+
+Use the most specific scope that matches the real convention.
+Do not add scoped rules just because directories exist.
+
+6. Configure tree and graph excludes
+
+Tree excludes affect directory and file discovery output.
+Graph excludes affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, and saved graph views.
+
+Built-in excludes already skip common noise such as node_modules, .git, dist, build, out, and .tmp.
+Add config excludes for repository-specific noise.
+
+For example, if the user often creates hard-copy directories or backup files before risky edits, those copies can make tree and graph output noisy.
+Exclude them explicitly:
+
+"inspect.tree.onlyDirs.exclude": [
+  "**/*copy",
+  "**/*copy/**"
+],
+"inspect.tree.files.exclude": [
+  "**/* copy.ts",
+  "**/*.generated.ts"
+],
+"inspect.graph.exclude": [
+  "**/* copy.ts",
+  "**/*.generated.ts",
+  "src/generated/**"
+]
+
+Prefer narrow patterns for known noise:
+- generated files;
+- local copy/backup folders;
+- build artifacts not already skipped by defaults;
+- vendored or checked-in output.
+
+These are common cases, not mandatory rules.
+If the repository needs one of these areas for reasoning or mutation impact checks, do not exclude it.
+
+Do not exclude broad source areas to make output smaller.
+If output is too large, use scope, depth, limit, graph view, or graph toggles first.
+
+7. Configure TypeScript config discovery
+
+AIB syncs and watches visible tsconfigs.
+Keep real app/package configs visible.
+Exclude nested workspaces, seed projects, snapshots, backups, copied apps, or other non-primary projects.
+
+Do not exclude real package/app configs just to reduce output.
+
+Check which TypeScript configs AIB will sync and watch:
+
+aib reveal tsconfigs +all
+
+If output includes non-primary projects, exclude them:
+
+"sync.tsconfig.exclude": [
+  "dev-seed/**",
+  "snapshots/**"
+]
+
+After editing aib.json, run:
+
+aib sync
+
+Then check again:
+
+aib reveal tsconfigs +all
+
+Visible tsconfigs should describe the active project surface.
+Excluded tsconfigs should be things the agent should not use for setup decisions.
+
+Use +nec only when you need to compare visible configs with config-excluded configs:
+
+aib reveal tsconfigs +nec
+
+8. Sync and verify
+
+After all aib.json edits, run:
+
+aib sync
+
+If sync fails, fix aib.json and rerun sync.
+
+Check the final config summary:
+
+aib config
+
+Run one compact tree batch using important aliases:
+
+aib inspect --stdin
+
+Input:
+tree @<important-alias> depth=3 +onlyDirs limit=80
+tree @<another-important-alias> depth=3 +onlyDirs limit=80
+
+Check final TypeScript config discovery:
+
+aib reveal tsconfigs
+
+Confirm:
+- aliases resolve;
+- obvious tree noise is hidden;
+- visible tsconfigs match the active project surface;
+- config sections are set intentionally.
+
+9. Note operational constraints
+
+Before reporting back, identify any constraints the user should know.
+
+Worktrees:
+AIB resolves config from the nearest parent aib.json.
+If the repository uses nested copied projects or worktrees inside the repo root, AIB may resolve the parent config.
+Do not set up AIB inside nested worktrees that should behave as independent repositories.
+Independent worktrees should live outside the main repo root or have their own intended aib.json boundary.
+
+TTL:
+Sessions and managed runtime are cleaned up after inactivity according to aib config session.
+Tell the user if you changed these defaults or left them as-is.
+
+Watchers:
+AIB watches aib.json and visible tsconfig files after sync.
+If config changes are not reflected, run aib sync.
+
+10. Report to user
+
+Report:
+- whether AIB config already existed or was initialized;
+- which aliases were added and why;
+- which importRules settings were added or intentionally left unset;
+- which tree/graph/tsconfig excludes were added;
+- whether sync and verification passed;
+- any worktree, TTL, watcher, or tsconfig discovery constraints the user should know.

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

@@ -0,0 +1,26 @@
+# Help Protocol
+
+After context compaction, always run:
+aib help help-protocol quick-map
+aib config aliases
+
+Use focused help when you would otherwise guess how a known AIB capability works.
+
+Reread bootstrap when you need to restore the overall AIB workflow faster than piecing it together from focused topics.
+If you just reread bootstrap, do not also read focused topics unless you need details that bootstrap does not cover.
+
+Do not reread bootstrap automatically if focused help is enough.
+
+If you are about to change import style across files, add or adopt tsconfig aliases, or clean imports repeatedly, read:
+aib help config-setup.import-normalize imports.normalize
+
+Refresh focused config help by signal:
+- repeated long paths: aib help config-setup.aliases
+- wrong move/modulePlan imports: aib help config-setup.import-rules
+- noisy tree/graph output: aib help config-setup.excludes
+- too many visible tsconfigs: aib help config-setup.tsconfigs
+
+When refreshing multiple areas, request them together instead of one by one.
+
+Example:
+aib help patterns mutation inspect inspect.file inspect.code imports.normalize

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

@@ -0,0 +1,38 @@
+# Inspect Cycles
+
+Use cycles to find import cycles in a file or directory scope.
+
+Cycles reports cyclic components, not every possible path through a dense graph.
+It classifies cycles as runtime, type-only, or mixed.
+
+Start broad with summary output.
+Use detail=imports when you need the import edges that explain a cycle.
+Use detail=files when file membership is enough.
+
+Controls:
+scope   file or directory scope
+files   focus cycles that include one or more files
+detail  summary|imports|files
+limit   max cyclic components shown
+
+Run:
+aib inspect cycles <scope>
+
+Inline:
+aib inspect cycles src/features --limit 20
+aib inspect cycles src/features --detail imports --limit 20
+aib inspect cycles --files src/features/service.ts --detail imports
+
+Stdin:
+aib inspect --stdin
+
+Input:
+cycles src/features limit=20
+cycles src/features detail=imports limit=20
+cycles scope=src/features files=[src/features/service.ts] detail=imports
+
+If output hides components and shows a view handle, inspect only the hidden part:
+
+aib view <handle> --offset 2 --limit 2
+aib view <handle> --index 4 --detail imports
+aib view <handle> --index 5 --detail files

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

@@ -23,6 +23,7 @@ incoming references/callers      usages
 file/module connectivity         graph
 compact directory layout         tree
 repeated declarations/helpers    duplicates
+local import cycles              cycles
 
 Prefer one batch DSL request for related questions.
 

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

@@ -3,23 +3,25 @@
 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
+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
-include   only matching files/dirs; include=[...]
+only      only matching files/dirs; only=[...]
+exclude   skip matching files/dirs; exclude=[...]
+ned       no-default-exclude; ignore built-in excludes; +ned
+nec       no-config-exclude; ignore aib.json tree excludes; +nec
 
 Run:
 aib inspect --stdin
 
 Input:
-tree src depth=4 +onlyDirs limit=200
-tree @svc depth=3 include=["**/*.ts"] exclude=["**/*.test.ts","**/* copy.ts"]
+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
 
 First pass in an unfamiliar codebase:
 tree src depth=5 +onlyDirs limit=200

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

@@ -12,6 +12,9 @@ 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.

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

@@ -12,6 +12,9 @@ Move is semantic; it moves supported declarations and updates affected imports/r
 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

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

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

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

@@ -1,6 +1,11 @@
 # 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:
@@ -42,124 +47,17 @@ 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.
+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.
 

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

@@ -1,11 +1,15 @@
 # Quick Read
 
-Use qr to read arbitrary text files with compact, cross-platform line windows.
+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.
 
-qr is not a replacement for inspect.
+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

package/dist/help/dsl/docs/quick-map.md

@@ -0,0 +1,30 @@
+# 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/dsl/docs/reveal.md

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