@automaton-labs/aib 0.0.7 → 0.0.9

package/dist/help/topics/quick-map.md

@@ -1,29 +1,41 @@
-Read:
-  qr              quick reads: ts, js, cmd, sh, json, log, txt, etc.
-  rg              use `aib rg -- <args>` instead of `rg <args>`
-  view            hidden/truncated output
+Run as: aib help <topic...>
 
-Inspect:
-  file
-  imports
-  exports
-  members
-  code
-  deps
-  usages
-  graph
-  tree
-  duplicates
-  cycles
+Help conventions:
+  help-format
 
-Mutate:
+Refresh workflow model:
+  basics patterns
+
+Core focused topics:
+  session
+  rules
+  selectors
+  dsl
+  inspect.shared
+  mutation.shared
+  recipes
+
+Feature topics:
+  inspect.file
+  inspect.imports
+  inspect.exports
+  inspect.members
+  inspect.code
+  inspect.deps
+  inspect.usages
+  inspect.graph
+  inspect.tree
+  inspect.duplicates
+  inspect.cycles
   rename
   move
+  moveToDir
+  renameFile
+  mutate.mixed        batch related mutation steps
   modulePlan
-  refactor batch
-  imports normalize
-
-Other:
-  config
-  prefs
-  reveal         tsconfig and tsconfig alias discovery
+  import.rebase
+  imports.normalize
+  view
+  qr
+  rg
+  reveal              tsconfig and tsconfig alias discovery

package/dist/help/topics/recipe.file-layout.md

@@ -1,13 +1,13 @@
-Assumption:
-You are changing whole-file layout.
-You are not moving TypeScript declarations or renaming TypeScript symbols.
-
+Assumption:
+You are changing whole-file layout.
+You are not moving TypeScript declarations or renaming TypeScript symbols.
+
 Related topics:
-aib help mutation file.move file.rename
-
-If you only need to move files, do not read file.rename.
-If you only need to rename files, do not read file.move.
+aib help mutation moveToDir renameFile
 
-Use focused topic syntax to express the file layout refactor.
-Do not move or rename files manually.
+If you only need to move files, do not read renameFile.
+If you only need to rename files, do not read moveToDir.
+
+Use focused topic syntax to express the file layout refactor.
+Do not move or rename files manually.
 Use AIB file mutations so references/imports are updated.

package/dist/help/topics/recipe.import-boundary.md

@@ -0,0 +1,90 @@
+Assumption:
+You are changing import boundaries, not only import style.
+
+Goal:
+Move eligible consumers toward or away from a barrel boundary.
+
+Choose direction:
+- useBarrel when a barrel should become the import boundary.
+- useDirect when consumers should stop importing through that barrel.
+
+Optional limits:
+Use the controls below only when the migration is intentionally partial.
+
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
+
+If a name is ambiguous, use selectors.
+
+Syntax:
+
+@scope <consumer-scope>
+imports.useBarrel <barrel-file> [pathExclude=[...]] [symbols=[...]]
+
+@scope <consumer-scope>
+imports.useDirect <barrel-file> [pathExclude=[...]] [symbols=[...]]
+
+Controls:
+
+@scope       consumer file or directory scope to scan
+pathExclude  consumer files, directories, or glob-like patterns to leave unchanged
+symbols      exported barrel names to update
+
+Use pathExclude for tests, generated files, fixtures, or migration-excluded areas.
+
+By default, do not list symbols.
+AIB reads the barrel and rewrites eligible imports for exported names it can resolve.
+Use symbols only when the request must affect a specific subset of the barrel surface.
+
+Run:
+aib mutate execute --stdin
+
+Use a barrel as the import boundary:
+
+Input:
+@scope src/features
+imports.useBarrel src/logs/index.ts
+
+Use direct source imports instead of a barrel:
+
+Input:
+@scope src/features
+imports.useDirect src/logs/index.ts
+
+Skip consumers that should not be rewritten:
+
+Input:
+@scope src/features
+imports.useBarrel src/logs/index.ts pathExclude=["**/*.test.ts","src/generated/**"]
+
+Limit the request to selected exported names:
+
+Input:
+@scope src/features
+imports.useDirect src/logs/index.ts symbols=[parseLogsQuery,LogsQuery]
+
+Compatibility
+
+Supported:
+- ES named imports
+- named re-exports
+- star re-exports
+- type-only named imports
+- aliased named re-exports
+
+Skipped or unsupported:
+- CommonJS require/module.exports
+- default re-exports
+- namespace imports
+- side-effect imports
+- default import parts
+
+Skipped imports are not rewritten.
+
+Split the migration only when different consumer areas need different boundaries,
+or when part of the repo should intentionally stay unchanged for this pass.

package/dist/help/topics/recipe.safe-artifact-probing.md

@@ -0,0 +1,66 @@
+You are about to run a tool, runtime, parser, compiler, formatter, linter, `require`, or `vm` probe against a generated, bundled, minified, dependency/vendor, lock/patch, or huge-line artifact.
+
+Do not print raw probe output directly.
+Capture stdout/stderr first, then read only a small byte-capped diagnostic.
+
+Run the probe into files:
+
+`<probe command> > <tmp-out> 2> <tmp-err>`
+
+Print status separately.
+Read a small byte-capped diagnostic from stderr.
+
+Example:
+
+`head -c 2000 <tmp-err>`
+
+Use an equivalent byte-capped read for the current shell when `head -c` is unavailable.
+
+Do not use line count as the safety boundary for unknown huge-line output.
+`tail -40` can still print a huge bundled source line.
+
+If the diagnostic is mostly raw source context, do not increase the cap.
+Change the probe shape.
+
+Use the diagnostic signal to narrow the next step:
+- exit code;
+- error name;
+- error message;
+- short stack frames;
+- path, line, symbol, option, or short literal.
+
+If the task is still "where is the relevant code?", use `recipe.unfamiliar-area` first.
+Return here before running a risky parser/runtime/tool probe.
+
+For JavaScript parse-only questions, prefer a syntax check before runtime execution:
+
+`node -c <artifact> > <tmp-out> 2> <tmp-err>`
+
+For JavaScript runtime questions, catch exceptions and print structured fields instead of raw stacks.
+
+Print:
+- error name;
+- error message;
+- a small number of short stack-frame-looking lines.
+
+Do not print raw `e.stack` for generated, bundled, minified, dependency/vendor, or huge-line artifacts.
+
+Example shape:
+
+```js
+try {
+  // run the smallest runtime probe that answers the question
+} catch (e) {
+  console.error(`${e?.name || "Error"}: ${e?.message || ""}`);
+  for (const line of String(e?.stack || "").split(/\r?\n/)) {
+    const text = line.trim();
+    if (text.startsWith("at ") && text.length < 500) {
+      console.error(text);
+    }
+  }
+  process.exitCode = 1;
+}
+```
+
+After a small diagnostic, continue with narrow reads/searches.
+Read artifact implementation only after the diagnostic points to a specific term, range, wrapper, entrypoint, or behavior.

package/dist/help/topics/recipe.unfamiliar-area.md

@@ -0,0 +1,62 @@
+The same task can be solved with broad output dumps or with structured narrowing.
+Use this recipe to spend context on signal: boundaries, candidate files, then exact slices.
+
+Start with directory structure and boundaries.
+Use `inspect.tree` with directories first:
+
+tree <scope> depth=3 +onlyDirs limit=120
+
+If the task explicitly requires a hidden/dependency/vendor/generated area, keep the scope narrow and only then disable excludes:
+
+tree <narrow-scope> depth=3 +onlyDirs limit=120 +ned +nec
+
+Do not start with broad `+ned +nec` over the repo root.
+
+Localize candidate files.
+If you have a concrete term, symbol, package name, error text, import specifier, or config key, use count search before full match output:
+
+aib rg -- -c "<pattern>" <scope>
+
+Use counts to pick a small set of candidate files before reading matches or file content.
+
+If you do not have a concrete search pattern yet, inspect the file layout instead of inventing broad patterns:
+
+tree <narrow-scope> depth=4 only=["**/*.ts","**/*.tsx","**/*.js","**/*.json"] limit=160
+
+Use the file layout to pick likely files or narrower directories, then continue with focused inspect or focused search.
+
+Map candidate files before implementation reads.
+For TS/JS candidates, inspect the strongest candidates first.
+
+Run:
+aib inspect --stdin
+
+Input:
+file <candidate-a.ts>
+file <candidate-b.ts>
+
+Use file output for declarations and ranges.
+
+Add imports only when dependency, wrapper, source, or "where does this come from" questions matter:
+
+imports <candidate-a.ts>
+
+Add exports only for public module surface, barrels, re-exports, export *, or boundary questions:
+
+exports <candidate-index.ts> +resolveStar
+
+Then read exact implementation slices with qr:
+
+aib qr <candidate-a.ts> s=<range-a>,<range-b>
+
+For non-TS/JS candidates, start with small qr windows:
+
+aib qr <candidate> h=80
+
+Then narrow with `s=` or `r=` as needed.
+Avoid `all` for files whose size/content is unknown.
+
+Read implementation only after you have a narrowed scope, candidate files, and ranges or windows.
+
+Focused help:
+aib help inspect.tree inspect.file inspect.imports inspect.exports qr rg

package/dist/help/topics/recipes.md

@@ -0,0 +1,18 @@
+Run as:
+aib help <recipe...>
+
+Read and use a recipe when one of these situations appears during regular work.
+
+Opportunistic triggers:
+
+- Trigger: you create, change, or adopt a barrel/import boundary
+  Read: recipe.import-boundary
+
+- Trigger: you are about to change file layout, move files, or rename files
+  Read: recipe.file-layout
+
+- Trigger: you are about to debug, modify, or extend code in an unfamiliar area
+  Read: recipe.unfamiliar-area
+
+- Trigger: you are about to run a tool or runtime probe against a generated, bundled, minified, dependency/vendor, lock/patch, or huge-line artifact
+  Read: recipe.safe-artifact-probing

package/dist/help/topics/rename.md

@@ -1,6 +1,11 @@
-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.
+Run mutation DSL through aib mutate.
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
 
 If a name is ambiguous, use selectors.
 Run help selectors to refresh selector syntax.
@@ -9,17 +14,12 @@ 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.
+Syntax:
+rename <oldName>-><newName> <oldName2>-><newName2>
+
+Run:
+aib mutate execute --stdin
 
-Run:
-aib rename execute --stdin
-
-Input:
-@file src/service.ts
+Input:
+@source src/service.ts
 rename oldName->newName OldService->NewService

package/dist/help/topics/renameFile.md

@@ -0,0 +1,34 @@
+Run mutation DSL through aib mutate.
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
+
+renameFile renames whole files.
+Use it when the filesystem layout is the intent.
+
+Syntax:
+renameFile <sourceFile>-><targetFile> <sourceFile2>-><targetFile2>
+
+Run:
+aib mutate execute --stdin
+
+Input:
+@base src
+renameFile svc/ws-cli.ts->cli.ts svc/ws-command.ts->command.ts
+renameFile svc/core/opt-build.ts->builder.ts
+
+How this resolves:
+- source files resolve from @base;
+- target names without a directory stay beside each source file.
+
+Rules:
+- @base sets the base directory for source files.
+- source file paths resolve from @base; cwd-relative paths are accepted when the @base path does not exist.
+- target names without a directory stay beside each source file.
+- target paths with a directory resolve from @base.
+- source paths and target paths may use `..`.
+- renameFile supports files, not directories.

package/dist/help/topics/rules.md

@@ -0,0 +1,24 @@
+Set the command timeout to 5 minutes for AIB requests.
+
+Use `aib rg -- <args>` instead of `rg <args>`.
+Do not use AIB aliases in `aib rg` arguments.
+
+Use aliases from `aib config aliases` as the normal path form for AIB requests.
+Exception: `aib rg` takes real shell paths.
+If AIB maps a full path to an alias in output, use the alias in the next request.
+
+Use matching recipes when their trigger appears during work.
+Do not treat `aib help recipes` as documentation only.
+
+Use `aib qr` for compact text reads: ts, js, cmd, sh, json, log, txt, etc.
+Use AIB path aliases when available.
+Batch paths and combine windows for the same file instead of repeating the path.
+Use `s=A:B,C:D,E` for inclusive slices.
+Use `r=A:B,C:D,E` for start+line-count ranges; a single start like `E` uses default 80 lines.
+Avoid `all` for files whose size/content is unknown; it can dump unnecessary context.
+
+Example:
+aib qr @svc/users.ts s=3:42,66:84,92 @scripts/a.txt h=80 @scripts/b.py r=300:50,500 .prettierrc all
+
+When AIB output shows `// aib-signal`, adjust the next request or workflow.
+Do not repeat the same inefficient pattern unchanged.

package/dist/host/capabilities.js

@@ -1 +1,56 @@
-"use strict";var o=exports&&exports.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.AIB_SUPPORTED_ACTIVATION_POLICIES=exports.AIB_SUPPORTED_INVOKE_MODES=exports.AIB_HOST_CAPABILITIES=exports.AIB_WORKER_ABI=void 0,exports.readHostCapabilities=i;const a=o(require("node:fs")),r=o(require("node:path"));exports.AIB_WORKER_ABI="1",exports.AIB_HOST_CAPABILITIES=["productStorage","jsonStdout","traceUploadLedger","backgroundSchedule","policyConfig","workerRegistry","workerBundleOta","cliPackageOta"],exports.AIB_SUPPORTED_INVOKE_MODES=["structured","process","stream"],exports.AIB_SUPPORTED_ACTIVATION_POLICIES=["ota-activation","cli-package-activation","extension-vsix-activation","ota-watch","ota-cleanup"];function i(e=n()){return{schemaVersion:1,hostVersion:s(e),workerAbi:exports.AIB_WORKER_ABI,platform:process.platform,arch:process.arch,nodeRuntime:`node-${process.versions.node.split(".")[0]}`,launcherProtocol:"1",daemonInvokeProtocol:"http-session-v1",supportedInvokeModes:exports.AIB_SUPPORTED_INVOKE_MODES,productStorageSchema:1,supportedActivationPolicies:exports.AIB_SUPPORTED_ACTIVATION_POLICIES,runtime:"cjs-node20",capabilities:exports.AIB_HOST_CAPABILITIES}}function n(){return r.default.resolve(__dirname,"..","..")}function s(e){try{const t=JSON.parse(a.default.readFileSync(r.default.join(e,"package.json"),"utf8"));return typeof t.version=="string"&&t.version.trim()?t.version:"0.0.0"}catch{return"0.0.0"}}
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIB_SUPPORTED_ACTIVATION_POLICIES = exports.AIB_SUPPORTED_INVOKE_MODES = exports.AIB_HOST_CAPABILITIES = exports.AIB_WORKER_ABI = void 0;
+exports.readHostCapabilities = readHostCapabilities;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.AIB_WORKER_ABI = "1";
+exports.AIB_HOST_CAPABILITIES = [
+    "productStorage",
+    "jsonStdout",
+    "traceUploadLedger",
+    "backgroundSchedule",
+    "policyConfig",
+    "workerRegistry",
+    "workerBundleOta",
+    "cliPackageOta"
+];
+exports.AIB_SUPPORTED_INVOKE_MODES = ["structured", "process", "stream"];
+exports.AIB_SUPPORTED_ACTIVATION_POLICIES = [
+    "ota-activation",
+    "cli-package-activation",
+    "ota-watch",
+    "ota-cleanup"
+];
+function readHostCapabilities(packageRoot = defaultPackageRoot()) {
+    return {
+        schemaVersion: 1,
+        hostVersion: readPackageVersion(packageRoot),
+        workerAbi: exports.AIB_WORKER_ABI,
+        platform: process.platform,
+        arch: process.arch,
+        nodeRuntime: `node-${process.versions.node.split(".")[0]}`,
+        launcherProtocol: "1",
+        daemonInvokeProtocol: "http-session-v1",
+        supportedInvokeModes: exports.AIB_SUPPORTED_INVOKE_MODES,
+        productStorageSchema: 1,
+        supportedActivationPolicies: exports.AIB_SUPPORTED_ACTIVATION_POLICIES,
+        runtime: "cjs-node20",
+        capabilities: exports.AIB_HOST_CAPABILITIES
+    };
+}
+function defaultPackageRoot() {
+    return node_path_1.default.resolve(__dirname, "..", "..");
+}
+function readPackageVersion(packageRoot) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(packageRoot, "package.json"), "utf8"));
+        return typeof parsed.version === "string" && parsed.version.trim() ? parsed.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}