@automaton-labs/aib 0.0.2 → 0.0.4

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

@@ -0,0 +1,277 @@
+# 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
+
+Run:
+
+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";
+- 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
+
+Set importRules to the import style this repository should use after move/modulePlan mutations.
+
+If the repository has one 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 import normalization
+
+Add importNormalize only for cleanup commands the agent is likely to run more than once.
+
+Use it when the repo has a clear normalization target:
+
+"importNormalize": [
+  {
+    "scope": "src",
+    "to": "shortestAlias",
+    "preferAlias": "@/*",
+    "exclude": [
+      "src/generated",
+      "src/**/dist"
+    ]
+  },
+  {
+    "scope": "scripts",
+    "to": "relative",
+    "exclude": [
+      "scripts/**/*.cjs",
+      "scripts/**/*.mjs"
+    ]
+  }
+]
+
+Choose scopes from real repo conventions.
+Do not copy importRules into importNormalize automatically.
+Leave it unset if normalization is not a repeated workflow.
+
+7. Configure tree and graph excludes
+
+Add excludes for noise the repository is known to contain.
+
+Use tree excludes for what the agent should not see while mapping folders.
+Use graph excludes for files that should not affect graph counts, hubs, entrypoints, leaves, edges, or 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.
+
+8. Configure TypeScript config discovery
+
+Check which TypeScript configs AIB will sync and watch:
+
+aib reveal tsconfigs +all
+
+If output includes nested workspaces, seed projects, snapshots, backups, copied apps, or other non-primary projects, exclude them:
+
+"sync.tsconfig.exclude": [
+  "dev-seed/**",
+  "snapshots/**"
+]
+
+Do not exclude real package/app configs just to reduce output.
+
+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
+
+9. 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.
+
+10. 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.
+
+11. Report to user
+
+Report:
+- whether AIB config already existed or was initialized;
+- which aliases were added and why;
+- which importRules/importNormalize 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/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/docs/patterns.md

@@ -154,10 +154,19 @@ 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.
+AIB has four config exclude fields:
+inspect.graph.exclude
+inspect.tree.files.exclude
+inspect.tree.onlyDirs.exclude
+sync.tsconfig.exclude
 
-Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.
+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.
+Tsconfig excludes affect which TypeScript configs AIB syncs and watches.
 
 Leave feedback while working.
 

package/dist/help/dsl/bootstrap.md

@@ -177,10 +177,19 @@ 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.
+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.
+Tsconfig excludes affect which TypeScript configs AIB syncs and watches.
 
 Leave feedback while working.
 
@@ -640,24 +649,25 @@ 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.
 
-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
-exclude   skip matching files/dirs
-include   only matching files/dirs; include=[...]
+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
-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
 
 Inspect Duplicates
 

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

@@ -0,0 +1,277 @@
+# 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
+
+Run:
+
+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";
+- 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
+
+Set importRules to the import style this repository should use after move/modulePlan mutations.
+
+If the repository has one 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 import normalization
+
+Add importNormalize only for cleanup commands the agent is likely to run more than once.
+
+Use it when the repo has a clear normalization target:
+
+"importNormalize": [
+  {
+    "scope": "src",
+    "to": "shortestAlias",
+    "preferAlias": "@/*",
+    "exclude": [
+      "src/generated",
+      "src/**/dist"
+    ]
+  },
+  {
+    "scope": "scripts",
+    "to": "relative",
+    "exclude": [
+      "scripts/**/*.cjs",
+      "scripts/**/*.mjs"
+    ]
+  }
+]
+
+Choose scopes from real repo conventions.
+Do not copy importRules into importNormalize automatically.
+Leave it unset if normalization is not a repeated workflow.
+
+7. Configure tree and graph excludes
+
+Add excludes for noise the repository is known to contain.
+
+Use tree excludes for what the agent should not see while mapping folders.
+Use graph excludes for files that should not affect graph counts, hubs, entrypoints, leaves, edges, or 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.
+
+8. Configure TypeScript config discovery
+
+Check which TypeScript configs AIB will sync and watch:
+
+aib reveal tsconfigs +all
+
+If output includes nested workspaces, seed projects, snapshots, backups, copied apps, or other non-primary projects, exclude them:
+
+"sync.tsconfig.exclude": [
+  "dev-seed/**",
+  "snapshots/**"
+]
+
+Do not exclude real package/app configs just to reduce output.
+
+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
+
+9. 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.
+
+10. 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.
+
+11. Report to user
+
+Report:
+- whether AIB config already existed or was initialized;
+- which aliases were added and why;
+- which importRules/importNormalize 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/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