@automaton-labs/aib 0.0.5 → 0.0.7

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

@@ -1,292 +0,0 @@
-# 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/json/docs/help-format.md

@@ -1,12 +0,0 @@
-# Help Format
-
-Inline commands below omit the aib prefix.
-Run them as: aib <command>
-
-Stdin examples show command and input separately to avoid shell-specific syntax.
-Stdin Run lines include the aib prefix to avoid confusion.
-
-PowerShell stdin shape:
-@'
-<input>
-'@ | aib <command> --stdin

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

@@ -1,26 +0,0 @@
-# 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/json/docs/imports.normalize.md

@@ -1,47 +0,0 @@
-# Imports Normalize
-
-Use imports normalize for explicit import-style cleanup.
-It rewrites resolved local import/export specifiers inside a chosen file or directory.
-
-Use importNormalize in aib.json for repeated defaults.
-
-Good for:
-- converting one area to aliases or relative imports
-- cleaning import style after manual edits or broad refactors
-- applying the same import style to a directory without hand-editing files
-- applying new tsconfig aliases after they are added
-
-Controls:
-scope        file/dir scope to normalize
-to           relative|alias|shortestAlias
-preferAlias  select one tsconfig paths pattern when several aliases can resolve the same file
-exclude      files, directories, or glob-like patterns to skip
-all          show all planned edits; avoid on broad directory scopes
-
-Run:
-aib imports normalize preview --stdin
-
-Input:
-{
-  "scope": "src/services",
-  "to": "shortestAlias",
-  "exclude": ["src/services/generated", "**/* copy.ts"]
-}
-
-Rewrite imports found inside src/core.
-When an imported file can be expressed through @features/*, prefer that alias.
-
-Run:
-aib imports normalize preview --stdin
-
-Input:
-{
-  "scope": "src/core",
-  "to": "alias",
-  "preferAlias": "@features/*"
-}
-
-With matching importNormalize config for this scope or a parent scope, use inline CLI commands:
-
-imports normalize preview @svc
-imports normalize execute @svc

package/dist/help/json/docs/inspect.code.md

@@ -1,41 +0,0 @@
-# Inspect Code
-
-Use code to fetch exact declarations or members.
-It returns focused code without reading the whole file.
-
-Good for:
-- reading a known function, class, method, or declaration
-- fetching several related code blocks in one request
-- keeping context focused on code needed for the current task
-
-Controls:
-file, entity, entities, parent, show, ranges
-
-Specific:
-show  include source output
-
-Defaults: +show +ranges
-Use -show for names/ranges only.
-Use -ranges for source without ranges.
-
-Prefs:
-inspect.code.maxNonEmptyLines
-
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "file": "src/service.ts",
-  "op": "code",
-  "requests": [
-    {
-      "entities": [
-        { "parent": "Service", "entities": ["render", "reset"] },
-        "normalize"
-      ],
-      "show": true,
-      "save": "service-focus"
-    }
-  ]
-}

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

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

@@ -1,46 +0,0 @@
-# Inspect Deps
-
-Use deps to see what one entity depends on inside its file.
-It separates type-only dependencies from runtime value dependencies.
-
-Good for:
-- checking what a symbol may need when moved or extracted
-- spotting nearby types, constants, or helpers tied to one entity
-- deciding whether one symbol is standalone or tied to nearby declarations
-- debugging mutation failures caused by local dependency shape
-
-Controls:
-file, entity, entities, parent
-
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "file": "src/service.ts",
-  "op": "deps",
-  "requests": [
-    { "entity": "createService" },
-    {
-      "entities": [
-        { "parent": "Service", "entities": ["render", "reset"] }
-      ]
-    }
-  ]
-}
-
-inspect deps src/service.ts Service
-
-Batch several symbols when you are planning a move:
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "file": "src/service.ts",
-  "requests": [
-    { "op": "deps", "entity": "Service" },
-    { "op": "deps", "entity": "ServiceOptions" },
-    { "op": "deps", "entity": "createService" }
-  ]
-}

package/dist/help/json/docs/inspect.duplicates.md

@@ -1,65 +0,0 @@
-# Inspect Duplicates
-
-Use duplicates to find repeated top-level names and exact declaration copies.
-It is useful when many files may contain copied local helpers, duplicated types, or repeated declarations.
-
-Start with summary for broad scopes.
-Use locations when you need files/lines.
-Use code only for duplicate names you are ready to inspect.
-
-Controls:
-scope, detail, limit, offset, kinds, entities, exclude, pathExclude
-
-Specific:
-entities    only these duplicate names/selectors
-exclude     skip these names/selectors
-pathExclude skip files or path/glob-like patterns
-kinds       selector kinds, e.g. f, t, c, etc.; kinds=[...]
-
-Summary scan:
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "scope": "src",
-  "detail": "summary",
-  "limit": 20
-}
-
-Inspect specific duplicate code:
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "scope": "src",
-  "detail": "code",
-  "entities": ["getBoolean", "WsOptions"]
-}
-
-Command shape:
-inspect duplicates <scope> [--detail summary|locations|code] [--limit N] [--offset N]
-
-Use JSON when filtering by several names:
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "scope": ["src/scripts", "tools"],
-  "detail": "locations",
-  "entities": ["getBoolean", "getNumberValue"],
-  "exclude": ["LegacyOptions"]
-}
-
-Use saved output when duplicate results are large:
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "scope": "src",
-  "detail": "summary",
-  "save": "duplicate-summary"
-}

package/dist/help/json/docs/inspect.exports.md

@@ -1,40 +0,0 @@
-# Inspect Exports
-
-Use exports to see the public API of one file.
-It answers what other files can import from that file.
-
-Important:
-inspect.file marks exported declarations already.
-
-Do not batch this for a plain implementation file:
-file src/service.ts
-exports src/service.ts
-
-Use exports when you need public module surface, barrels, re-exports, export *, or resolveStar.
-
-Good for:
-- checking a module boundary or public surface
-- understanding facade/barrel files
-- resolving export * when the local file only re-exports from elsewhere
-- comparing API shape when public imports matter
-
-Controls:
-file, ranges, resolveStar
-
-Specific:
-resolveStar  resolve export * through re-exported modules; +resolveStar
-
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "op": "exports",
-  "file": "src/service.ts",
-  "requests": [
-    { "ranges": true },
-    { "file": "src/index.ts", "resolveStar": true }
-  ]
-}
-
-inspect exports src/service.ts [--ranges] [--resolve-star]

package/dist/help/json/docs/inspect.file.md

@@ -1,38 +0,0 @@
-# Inspect File
-
-Use file to map top-level declarations physically present in one file.
-Exported declarations are marked in the output.
-It shows what lives in the file before you decide whether to read code.
-
-Good for:
-- mapping an unfamiliar file
-- listing top-level declarations
-- checking whether a file contains real declarations or mostly re-exports
-
-Do not add limit just in case.
-file output is compact and most files have far fewer than 100 top-level declarations.
-Use limit only after file output is actually too large.
-
-Controls:
-file, ranges, localOnly
-
-Specific:
-localOnly   show local declarations and reexports without resolving facade API; +localOnly
-
-Defaults: +ranges
-Use -ranges to show names without ranges.
-
-Run:
-aib inspect --stdin
-
-Input:
-{
-  "op": "file",
-  "file": "src/service.ts",
-  "requests": [
-    { "ranges": true },
-    { "file": "src/index.ts", "localOnly": true }
-  ]
-}
-
-inspect file src/service.ts [--ranges] [--local-only]