@automaton-labs/aib 0.0.3 → 0.0.5

package/dist/help/topics/config-setup.aliases.md

@@ -0,0 +1,54 @@
+If you have not just checked the full config, check current aliases:
+
+aib config aliases
+
+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.
+
+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"
+}
+
+After editing aib.json, run:
+
+aib sync
+
+Verify aliases with a small tree or inspect request:
+
+aib inspect --stdin
+
+Input:
+tree @<alias> depth=3 +onlyDirs limit=80

package/dist/help/topics/config-setup.excludes.md

@@ -0,0 +1,43 @@
+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.
+
+After editing aib.json, run:
+
+aib sync
+
+Then verify with a compact tree request and the graph view that was noisy.
+
+If excluded paths still appear, check the glob pattern against repo-relative paths.
+If important source disappeared, narrow or remove the exclude.

package/dist/help/topics/config-setup.import-normalize.md

@@ -0,0 +1,84 @@
+Configure import normalization intent.
+
+importNormalize defines default normalization rules for explicit aib imports normalize commands.
+Use it before broad or important import cleanup so the scope, target style, preferred alias, and excludes are stored in aib.json instead of repeated in command arguments.
+
+It does not run automatically during move/modulePlan.
+Use importRules for mutation-time import cleanup.
+
+Set importNormalize when the intended cleanup has project meaning:
+- adopting a new tsconfig alias across a project area;
+- converting an area to aliases;
+- converting scripts/tools or extracted modules to relative imports;
+- excluding generated or bundled output from normalization.
+
+For tiny one-file checks, inline options are fine.
+Before wider cleanup, put the intended rule in config and preview the smallest useful scope.
+
+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
+
+Alias cleanup:
+
+"importNormalize": [
+  {
+    "scope": "src",
+    "to": "shortestAlias",
+    "preferAlias": "@/*",
+    "exclude": [
+      "src/generated",
+      "src/**/dist"
+    ]
+  }
+]
+
+Relative cleanup for scripts/tools:
+
+"importNormalize": [
+  {
+    "scope": "scripts",
+    "to": "relative",
+    "exclude": [
+      "scripts/**/*.cjs",
+      "scripts/**/*.mjs"
+    ]
+  }
+]
+
+If you have not just checked config rules, run:
+
+aib config rules
+
+After editing aib.json, run:
+
+aib sync
+
+Then preview the smallest useful scope before applying:
+
+aib imports normalize preview <scope>
+
+Preview shows counts, sample import rewrites, a planId, and the apply command.
+It does not change project files.
+
+If preview changes imports outside the intended area, narrow scope or add exclude.
+
+If preview does not use the expected alias, check tsconfig aliases:
+
+aib reveal tsaliases
+
+If the config and aliases look correct but preview still looks stale or strange, run:
+
+aib sync
+
+Then preview again.

package/dist/help/topics/config-setup.import-rules.md

@@ -0,0 +1,94 @@
+Use this when move/modulePlan creates imports that do not match the repository style.
+
+Do not keep fixing the same generated import style by hand.
+Tune importRules, sync config, then retry the smallest useful mutation before continuing larger mutation work.
+
+Check current config:
+
+aib config 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.
+
+After editing aib.json, run:
+
+aib sync
+
+Then rerun the smallest affected move/modulePlan preview or execute request.
+If imports are still wrong, update importRules again before doing more manual cleanup.

package/dist/help/topics/config-setup.tsconfigs.md

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

package/dist/help/topics/first-setup.md

@@ -0,0 +1,290 @@
+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/topics/help-protocol.md

@@ -0,0 +1,24 @@
+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/topics/inspect.cycles.md

@@ -0,0 +1,36 @@
+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/topics/inspect.md

@@ -21,6 +21,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/topics/inspect.tree.md

@@ -1,20 +1,22 @@
 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