@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/session/session-health.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSessionHealthPayload = buildSessionHealthPayload;
+exports.isReusableSessionHealth = isReusableSessionHealth;
+exports.isDrainingSessionHealth = isDrainingSessionHealth;
+function buildSessionHealthPayload(pid, runtime) {
+    return {
+        ok: true,
+        pid,
+        runtime
+    };
+}
+/** Old daemons without runtime diagnostics remain reusable. */
+function isReusableSessionHealth(health) {
+    if (health?.ok !== true)
+        return false;
+    const runtime = readRuntime(health);
+    return runtime?.acceptingRequests !== false;
+}
+function isDrainingSessionHealth(health) {
+    return readRuntime(health)?.acceptingRequests === false;
+}
+function readRuntime(health) {
+    return health?.runtime && typeof health.runtime === "object" && !Array.isArray(health.runtime)
+        ? health.runtime
+        : null;
+}

package/dist/shared/agent-text.js

@@ -1 +1,29 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.AGENT_TEXT_FIELD=void 0,exports.attachAgentText=T,exports.readAgentText=n,exports.stripAgentText=r,exports.AGENT_TEXT_FIELD="__aibText";function T(t,e){return e?{...t,[exports.AGENT_TEXT_FIELD]:e}:t}function n(t){const e=t[exports.AGENT_TEXT_FIELD];return typeof e=="string"&&e!==""?e:null}function r(t){if(t[exports.AGENT_TEXT_FIELD]===void 0)return t;const e={...t};return delete e[exports.AGENT_TEXT_FIELD],e}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TEXT_FIELD = void 0;
+exports.attachAgentText = attachAgentText;
+exports.readAgentText = readAgentText;
+exports.stripAgentText = stripAgentText;
+const presentation_1 = require("../agent-dx/presentation");
+exports.AGENT_TEXT_FIELD = "__aibText";
+function attachAgentText(payload, text) {
+    if (!text) {
+        return payload;
+    }
+    return {
+        ...payload,
+        [exports.AGENT_TEXT_FIELD]: (0, presentation_1.appendAgentDxText)(text, payload)
+    };
+}
+function readAgentText(payload) {
+    const value = payload[exports.AGENT_TEXT_FIELD];
+    return typeof value === "string" && value !== "" ? value : null;
+}
+function stripAgentText(payload) {
+    if (payload[exports.AGENT_TEXT_FIELD] === undefined) {
+        return payload;
+    }
+    const copy = { ...payload };
+    delete copy[exports.AGENT_TEXT_FIELD];
+    return copy;
+}

package/dist/shared/errors.js

@@ -1,30 +1,496 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.CliError=void 0,exports.errorPayload=g;const p=require("./agent-text"),m=require("./stdin-examples");class f extends Error{code;details;constructor(n,i,s){super(i),this.code=n,this.details=s}}exports.CliError=f;function _(e){return Array.isArray(e)&&e.every(n=>n!==null&&typeof n=="object"&&typeof n.kind=="string"&&typeof n.description=="string")}function l(e){return e===null||typeof e=="string"||typeof e=="number"||typeof e=="boolean"?e:Array.isArray(e)?e.map(n=>l(n)):e&&typeof e=="object"?Object.fromEntries(Object.entries(e).map(([n,i])=>[n,l(i)])):String(e)}function A(e){if(!e||typeof e!="object"||Array.isArray(e))return null;const n=e.hints;return _(n)?l(n):null}function I(e){return!!(e&&typeof e=="object"&&Array.isArray(e.issues))}function N(e){return!e||e.length===0?"<root>":e.map(n=>String(n)).join(".")}function h(e){return e.issues.map(n=>({path:N(n.path),message:typeof n.message=="string"?n.message:"Invalid value.",...typeof n.code=="string"?{code:n.code}:{}}))}function g(e){if(e instanceof f){const n={ok:!1,code:e.code,error:e.message,details:e.details?l(e.details):null},i=S(e);i&&(n[p.AGENT_TEXT_FIELD]=i);const s=A(e.details);return s?{...n,hints:s}:n}return I(e)?{ok:!1,code:"INVALID_INPUT",error:"Input JSON does not match the expected command shape.",details:{issues:h(e)}}:{ok:!1,code:"UNEXPECTED_ERROR",error:e instanceof Error?e.message:String(e),details:null}}function S(e){if(e.code==="EMPTY_STDIN")return["stdin payload is empty","",(0,m.formatStdinExamples)({includeQr:!0})].join(`
-`);if(e.code==="INVALID_STDIN_DSL"){const n=o(e.details),i=c(n.cause);return["invalid DSL stdin",...i?["",i]:[],"","Fix the DSL line and rerun the command."].join(`
-`)}if(e.code==="INVALID_STDIN_FORMAT")return["invalid stdin format","","Use:","--stdin-format auto","--stdin-format dsl"].join(`
-`);if(e.code==="INPUT_SOURCE_CONFLICT"||e.code.endsWith("_INPUT_SOURCE_CONFLICT"))return["input source conflict","","Use only one input source:","--stdin","--from <handle-or-file>","--from-json <file>","--from-dsl <file>"].join(`
-`);if(e.code==="INPUT_FROM_UNSUPPORTED")return["file input is not supported for this command","","Run the command without --from."].join(`
-`);if(e.code==="INPUT_STDIN_UNSUPPORTED")return["stdin input is not supported for this command","","Run the command without --stdin."].join(`
-`);if(e.code==="STDIN_DSL_COMMAND_MISMATCH")return["DSL command mismatch","",e.message,"","Run the command that matches the DSL intent, or change the DSL operation."].join(`
-`);if(e.code==="STDIN_DSL_UNSUPPORTED")return["DSL stdin is not supported for this command","","Use JSON input for this command, or run a DSL-capable command."].join(`
-`);if(e.code.startsWith("INVALID_")&&e.code.endsWith("_JSON_FILE")){const n=o(e.details),i=c(n.file);return["input file could not be read",...i?["",`file: ${i}`]:[],"","Check the path or saved input handle."].join(`
-`)}if(e.code==="UNKNOWN_COMMAND"){const n=o(e.details),i=Array.isArray(n.availableCommands)?n.availableCommands.filter(a=>typeof a=="string"):[],s=["help","config","sync","inspect","modulePlan","move","rename","imports","session","feedback"],t=i.length>0?s.filter(a=>a==="config"||i.includes(a)):s;return[e.message.replace(/^Unknown command:/,"unknown command:"),...t.length>0?["",`Common commands: ${t.join(", ")}`]:[],"","Run:","aib help"].join(`
-`)}if(e.code==="HELP_TOPIC_NOT_FOUND")return e.message;if(e.code==="INVALID_INSPECT_OP")return["invalid inspect operation","","Use: file, imports, exports, members, code, deps, usages, duplicates, graph, tree, cycles","","Example:","aib inspect file src/service.ts"].join(`
-`);if(e.code==="MODULE_PLAN_SOURCE_REQUIRED")return["modulePlan needs a source file","","DSL:","@source src/large-service.ts","module src/large-service.core.ts: LargeService createLargeService"].join(`
-`);if(e.code==="MODULE_PLAN_MODULES_REQUIRED")return["modulePlan needs at least one target module","","DSL:","@source src/large-service.ts","module src/large-service.core.ts: LargeService createLargeService"].join(`
-`);if(e.code==="NORMALIZE_IMPORTS_SCOPE_REQUIRED")return["imports normalize needs a file or directory scope","","DSL:","imports.normalize scope=src/features to=shortestAlias","","CLI:","aib imports normalize preview src/features"].join(`
-`);if(e.code==="INVALID_NORMALIZE_IMPORTS_MODE")return["imports normalize --to expects relative, alias, or shortestAlias","","Example:","aib imports normalize preview src/features --to shortestAlias"].join(`
-`);if(e.code==="WORKSPACE_ROOT_NOT_INITIALIZED")return["aib workspace not initialized","","No aib.json was found.","","If you are a user:","ask your agent to set up AIB for this repo:","aib help first-setup","","If you are an agent:","run:","aib help first-setup","","Then follow the setup from the intended repository root."].join(`
-`);if(e.code==="CONFIG_UPGRADE_CONFIG_NOT_FOUND")return["aib config upgrade skipped","","There is no aib.json config to upgrade in this directory tree.","","If this is the wrong directory:","go into the repository that already has aib.json, then run:","aib config upgrade","","If this is the repository you want to set up:","ask your agent:","Set up AIB in this repo. Start with `aib help first-setup`."].join(`
-`);if(e.code==="EXECUTION_NOT_FOUND"||e.code==="MODULE_PLAN_EXECUTION_NOT_FOUND"||e.code==="REFACTOR_BATCH_EXECUTION_NOT_FOUND"){const n=o(e.details);return[`execution not found: ${c(n.executionId)??"last"}`,"","No execution status exists for this id.","Run a long mutation first, or check the execution id."].join(`
-`)}if(e.code==="SESSION_HANDLE_NOT_FOUND"||e.code==="SESSION_RESULT_NOT_FOUND"){const n=o(e.details),i=c(n.handle)??"unknown",s=c(n.sessionDir);return[`handle not found: ${i}`,...s?["",`session: ${s}`]:[],"","The artifact may have been cleared or was never saved."].join(`
-`)}if(e.code==="SESSION_WORKSPACE_NOT_INITIALIZED")return["Session workspace is not initialized.","","Create a session:","aib session init --name <name>","","Refresh session guidance:","aib help session"].join(`
-`);if(e.code==="AMBIGUOUS_ENTITY_SELECTOR")return E(e);if(e.code==="INVALID_PATH_ALIAS_TARGET"||e.code==="SESSION_ALIASES_SET_USAGE")return["invalid path alias","","Use:","aib session aliases set <name> <path>","","Example:","aib session aliases set svc src/services"].join(`
-`);if(e.code==="AIB_CONFIG_INVALID"||e.code==="INVALID_PATH_ALIASES"||e.code==="INVALID_PATH_ALIAS_NAME"||e.code==="INVALID_PATH_ALIAS_TARGET"||e.code==="RESERVED_PATH_ALIAS_NAME")return y(e);if(e.code==="UNKNOWN_SESSION_PREF"){const n=o(e.details),i=Array.isArray(n.available)?n.available.filter(s=>typeof s=="string"):[];return[e.message.toLowerCase(),...i.length>0?["","Available prefs:",...i.slice(0,12).map(s=>`- ${s}`),...i.length>12?[`+ ${i.length-12} more`]:[]]:[],"","Run:","aib session prefs get --all"].join(`
-`)}if(e.code==="INVALID_SESSION_PREF_VALUE")return["invalid session preference value","",e.message,"","Run:","aib session prefs get --all"].join(`
-`);if(e.code==="UNKNOWN_SESSION_PREFS_COMMAND")return["unknown session prefs command","","Use:","aib session prefs get","aib session prefs set <key> <value>","aib session prefs clear [key]"].join(`
-`);if(e.code==="UNKNOWN_SESSION_ALIASES_COMMAND")return["unknown session aliases command","","Use:","aib session aliases get","aib session aliases set <name> <path>","aib session aliases clear [name]"].join(`
-`);if(e.code==="UNKNOWN_PATH_ALIAS"){const n=o(e.details),i=c(n.alias),s=Array.isArray(n.available)?n.available.filter(t=>typeof t=="string"):[];return[`unknown AIB path alias: @${i??""}`,"",s.length>0?`Available aliases: ${s.map(t=>`@${t}`).join(", ")}`:"No AIB path aliases are configured.",...s.length>0?["Run:","aib sync"]:["Check config:","aib config","or run:","aib sync"]].join(`
-`)}return null}function E(e){const n=o(e.details),i=Array.isArray(n.ambiguities)?n.ambiguities.filter(t=>t!==null&&typeof t=="object"&&!Array.isArray(t)):[];if(i.length>0){const t=i.map(r=>c(r.entity)).filter(r=>r!==null),a=[t.length===1?`ambiguous entity: ${t[0]}`:`ambiguous entities: ${t.join(", ")}`,"","Use available:"];for(const r of i){const d=Array.isArray(r.suggestions)?r.suggestions.filter(u=>typeof u=="string"&&u.length>0):[];d.length>0&&a.push(`- ${d.join(", ")}`)}return a.join(`
-`)}const s=Array.isArray(n.suggestions)?n.suggestions.filter(t=>typeof t=="string"&&t.length>0):[];return[e.message,...s.length>0?["","Use available:",`- ${s.join(", ")}`]:[]].join(`
-`)}function y(e){const n=["aib config invalid","",e.message];if(e.code==="INVALID_PATH_ALIAS_NAME"&&n.push("Use alias names without @, for example:",'"pathAliases": {','  "svc": "src/services"',"}"),e.code==="RESERVED_PATH_ALIAS_NAME"){const i=o(e.details),s=Array.isArray(i.reserved)?i.reserved.filter(t=>typeof t=="string"):[];s.length>0&&n.push(`Reserved aliases: ${s.join(", ")}`)}return n.push("","Edit aib.json, then run:","aib sync"),n.join(`
-`)}function o(e){return e&&typeof e=="object"&&!Array.isArray(e)?e:{}}function c(e){return typeof e=="string"&&e.length>0?e:null}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliError = void 0;
+exports.errorPayload = errorPayload;
+const agent_text_1 = require("./agent-text");
+const stdin_examples_1 = require("./stdin-examples");
+class CliError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+exports.CliError = CliError;
+function isHintArray(value) {
+    return Array.isArray(value) && value.every((item) => item !== null &&
+        typeof item === "object" &&
+        typeof item.kind === "string" &&
+        typeof item.description === "string");
+}
+function toJsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => toJsonValue(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJsonValue(item)]));
+    }
+    return String(value);
+}
+function extractHints(details) {
+    if (!details || typeof details !== "object" || Array.isArray(details)) {
+        return null;
+    }
+    const hints = details.hints;
+    return isHintArray(hints) ? toJsonValue(hints) : null;
+}
+function isZodLikeError(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        Array.isArray(error.issues));
+}
+function formatZodPath(path) {
+    if (!path || path.length === 0) {
+        return "<root>";
+    }
+    return path.map((part) => String(part)).join(".");
+}
+function formatZodIssues(error) {
+    return error.issues.map((issue) => ({
+        path: formatZodPath(issue.path),
+        message: typeof issue.message === "string" ? issue.message : "Invalid value.",
+        ...(typeof issue.code === "string" ? { code: issue.code } : {})
+    }));
+}
+function errorPayload(error) {
+    if (error instanceof CliError) {
+        const payload = {
+            ok: false,
+            code: error.code,
+            error: error.message,
+            details: error.details ? toJsonValue(error.details) : null
+        };
+        const agentText = formatErrorAgentText(error);
+        if (agentText) {
+            payload[agent_text_1.AGENT_TEXT_FIELD] = agentText;
+        }
+        const hints = extractHints(error.details);
+        return hints ? { ...payload, hints } : payload;
+    }
+    if (isZodLikeError(error)) {
+        return {
+            ok: false,
+            code: "INVALID_INPUT",
+            error: "Input JSON does not match the expected command shape.",
+            details: {
+                issues: formatZodIssues(error)
+            }
+        };
+    }
+    return {
+        ok: false,
+        code: "UNEXPECTED_ERROR",
+        error: error instanceof Error ? error.message : String(error),
+        details: null
+    };
+}
+function formatErrorAgentText(error) {
+    if (error.code === "INSPECT_TREE_SCOPE_REQUIRED") {
+        return error.message;
+    }
+    if (error.code === "EMPTY_STDIN") {
+        return [
+            "stdin payload is empty",
+            "",
+            (0, stdin_examples_1.formatStdinExamples)({ includeQr: true })
+        ].join("\n");
+    }
+    if (error.code === "INVALID_STDIN_DSL") {
+        const details = readDetailsObject(error.details);
+        const cause = readString(details.cause);
+        return [
+            "invalid DSL stdin",
+            ...(cause ? ["", cause] : []),
+            "",
+            "Fix the DSL line and rerun the command."
+        ].join("\n");
+    }
+    if (error.code === "INVALID_STDIN_FORMAT") {
+        return [
+            "invalid stdin format",
+            "",
+            "Use:",
+            "--stdin-format auto",
+            "--stdin-format dsl"
+        ].join("\n");
+    }
+    if (error.code === "INPUT_SOURCE_CONFLICT" || error.code.endsWith("_INPUT_SOURCE_CONFLICT")) {
+        return [
+            "input source conflict",
+            "",
+            "Use only one input source:",
+            "--stdin",
+            "--from <handle-or-file>",
+            "--from-json <file>",
+            "--from-dsl <file>"
+        ].join("\n");
+    }
+    if (error.code === "INPUT_FROM_UNSUPPORTED") {
+        return [
+            "file input is not supported for this command",
+            "",
+            "Run the command without --from."
+        ].join("\n");
+    }
+    if (error.code === "INPUT_STDIN_UNSUPPORTED") {
+        return [
+            "stdin input is not supported for this command",
+            "",
+            "Run the command without --stdin."
+        ].join("\n");
+    }
+    if (error.code === "STDIN_DSL_COMMAND_MISMATCH") {
+        return [
+            "DSL command mismatch",
+            "",
+            error.message,
+            "",
+            "Run the command that matches the DSL intent, or change the DSL operation."
+        ].join("\n");
+    }
+    if (error.code === "STDIN_DSL_UNSUPPORTED") {
+        return [
+            "DSL stdin is not supported for this command",
+            "",
+            "Use JSON input for this command, or run a DSL-capable command."
+        ].join("\n");
+    }
+    if (error.code.startsWith("INVALID_") && error.code.endsWith("_JSON_FILE")) {
+        const details = readDetailsObject(error.details);
+        const file = readString(details.file);
+        return [
+            "input file could not be read",
+            ...(file ? ["", `file: ${file}`] : []),
+            "",
+            "Check the path or saved input handle."
+        ].join("\n");
+    }
+    if (error.code === "UNKNOWN_COMMAND") {
+        const details = readDetailsObject(error.details);
+        const available = Array.isArray(details.availableCommands)
+            ? details.availableCommands.filter((item) => typeof item === "string")
+            : [];
+        const commonCommands = [
+            "help",
+            "config",
+            "sync",
+            "inspect",
+            "modulePlan",
+            "move",
+            "rename",
+            "mutate",
+            "imports",
+            "session",
+            "feedback"
+        ];
+        const visible = available.length > 0
+            ? commonCommands.filter((item) => item === "config" || available.includes(item))
+            : commonCommands;
+        return [
+            error.message.replace(/^Unknown command:/, "unknown command:"),
+            ...(visible.length > 0 ? ["", `Common commands: ${visible.join(", ")}`] : []),
+            "",
+            "Run:",
+            "aib help"
+        ].join("\n");
+    }
+    if (error.code === "HELP_TOPIC_NOT_FOUND") {
+        return error.message;
+    }
+    if (error.code === "INVALID_INSPECT_OP") {
+        return [
+            "invalid inspect operation",
+            "",
+            "Use: file, imports, exports, members, code, deps, usages, duplicates, graph, tree, cycles",
+            "",
+            "Example:",
+            "aib inspect file src/service.ts"
+        ].join("\n");
+    }
+    if (error.code === "MODULE_PLAN_SOURCE_REQUIRED") {
+        return [
+            "modulePlan needs a source file",
+            "",
+            "DSL:",
+            "@source src/large-service.ts",
+            "module src/large-service.core.ts: LargeService createLargeService"
+        ].join("\n");
+    }
+    if (error.code === "MODULE_PLAN_MODULES_REQUIRED") {
+        return [
+            "modulePlan needs at least one target module",
+            "",
+            "DSL:",
+            "@source src/large-service.ts",
+            "module src/large-service.core.ts: LargeService createLargeService"
+        ].join("\n");
+    }
+    if (error.code === "NORMALIZE_IMPORTS_SCOPE_REQUIRED") {
+        return [
+            "imports.normalize needs a file or directory scope",
+            "",
+            "Input:",
+            "@scope src/features",
+            "imports.normalize to=shortestAlias",
+            "",
+            "Run:",
+            "aib mutate preview --stdin",
+            "aib mutate execute --stdin"
+        ].join("\n");
+    }
+    if (error.code === "IMPORTS_NORMALIZE_MUTATE_ONLY") {
+        return [
+            "imports.normalize is available through aib mutate.",
+            "",
+            "Input:",
+            "@scope src/features",
+            "imports.normalize to=shortestAlias",
+            "",
+            "Run:",
+            "aib mutate preview --stdin",
+            "aib mutate execute --stdin"
+        ].join("\n");
+    }
+    if (error.code === "INVALID_NORMALIZE_IMPORTS_MODE") {
+        return [
+            "imports.normalize to= expects relative, alias, or shortestAlias",
+            "",
+            "Input:",
+            "@scope src/features",
+            "imports.normalize to=shortestAlias",
+            "",
+            "Run:",
+            "aib mutate preview --stdin"
+        ].join("\n");
+    }
+    if (error.code === "IMPORT_REBASE_BARREL_AMBIGUOUS") {
+        const details = readDetailsObject(error.details);
+        const candidates = Array.isArray(details.candidates)
+            ? details.candidates.filter((item) => typeof item === "string" && item.length > 0)
+            : [];
+        return [
+            error.message,
+            ...(candidates.length > 0
+                ? ["", "Choose an explicit barrel file:", ...candidates]
+                : []),
+            "",
+            "Pass the exact barrel file path."
+        ].join("\n");
+    }
+    if (error.code === "WORKSPACE_ROOT_NOT_INITIALIZED") {
+        return [
+            "aib workspace not initialized",
+            "",
+            "No aib.json was found.",
+            "",
+            "If you are a user:",
+            "ask your agent to set up AIB for this repo:",
+            "aib help first-setup",
+            "",
+            "If you are an agent:",
+            "run:",
+            "aib help first-setup",
+            "",
+            "Then follow the setup from the intended repository root."
+        ].join("\n");
+    }
+    if (error.code === "CONFIG_UPGRADE_CONFIG_NOT_FOUND") {
+        return [
+            "aib config upgrade skipped",
+            "",
+            "There is no aib.json config to upgrade in this directory tree.",
+            "",
+            "If this is the wrong directory:",
+            "go into the repository that already has aib.json, then run:",
+            "aib config upgrade",
+            "",
+            "If this is the repository you want to set up:",
+            "ask your agent:",
+            "Set up AIB in this repo. Start with `aib help first-setup`."
+        ].join("\n");
+    }
+    if (error.code === "EXECUTION_NOT_FOUND" || error.code === "MODULE_PLAN_EXECUTION_NOT_FOUND" || error.code === "REFACTOR_BATCH_EXECUTION_NOT_FOUND") {
+        const details = readDetailsObject(error.details);
+        const executionId = readString(details.executionId) ?? "last";
+        return [
+            `execution not found: ${executionId}`,
+            "",
+            "No execution status exists for this id.",
+            "Run a long mutation first, or check the execution id."
+        ].join("\n");
+    }
+    if (error.code === "SESSION_HANDLE_NOT_FOUND" || error.code === "SESSION_RESULT_NOT_FOUND") {
+        const details = readDetailsObject(error.details);
+        const handle = readString(details.handle) ?? "unknown";
+        const sessionDir = readString(details.sessionDir);
+        return [
+            `handle not found: ${handle}`,
+            ...(sessionDir ? ["", `session: ${sessionDir}`] : []),
+            "",
+            "The artifact may have been cleared or was never saved."
+        ].join("\n");
+    }
+    if (error.code === "SESSION_WORKSPACE_NOT_INITIALIZED") {
+        return [
+            "Session workspace is not initialized.",
+            "",
+            "Create a session:",
+            "aib session init --name <name>",
+            "",
+            "Refresh session guidance:",
+            "aib help session"
+        ].join("\n");
+    }
+    if (error.code === "AMBIGUOUS_ENTITY_SELECTOR") {
+        return formatAmbiguousEntitySelectorText(error);
+    }
+    if (error.code === "INVALID_PATH_ALIAS_TARGET" || error.code === "SESSION_ALIASES_SET_USAGE") {
+        return [
+            "invalid path alias",
+            "",
+            "Use:",
+            "aib session aliases set <name> <path>",
+            "",
+            "Example:",
+            "aib session aliases set svc src/services"
+        ].join("\n");
+    }
+    if (error.code === "AIB_CONFIG_INVALID" ||
+        error.code === "INVALID_PATH_ALIASES" ||
+        error.code === "INVALID_PATH_ALIAS_NAME" ||
+        error.code === "INVALID_PATH_ALIAS_TARGET" ||
+        error.code === "RESERVED_PATH_ALIAS_NAME") {
+        return formatConfigErrorText(error);
+    }
+    if (error.code === "UNKNOWN_SESSION_PREF") {
+        const details = readDetailsObject(error.details);
+        const available = Array.isArray(details.available)
+            ? details.available.filter((item) => typeof item === "string")
+            : [];
+        return [
+            error.message.toLowerCase(),
+            ...(available.length > 0
+                ? ["", "Available prefs:", ...available.slice(0, 12).map((item) => `- ${item}`), ...(available.length > 12 ? [`+ ${available.length - 12} more`] : [])]
+                : []),
+            "",
+            "Run:",
+            "aib session prefs get --all"
+        ].join("\n");
+    }
+    if (error.code === "INVALID_SESSION_PREF_VALUE") {
+        return [
+            "invalid session preference value",
+            "",
+            error.message,
+            "",
+            "Run:",
+            "aib session prefs get --all"
+        ].join("\n");
+    }
+    if (error.code === "UNKNOWN_SESSION_PREFS_COMMAND") {
+        return [
+            "unknown session prefs command",
+            "",
+            "Use:",
+            "aib session prefs get",
+            "aib session prefs set <key> <value>",
+            "aib session prefs clear [key]"
+        ].join("\n");
+    }
+    if (error.code === "UNKNOWN_SESSION_ALIASES_COMMAND") {
+        return [
+            "unknown session aliases command",
+            "",
+            "Use:",
+            "aib session aliases get",
+            "aib session aliases set <name> <path>",
+            "aib session aliases clear [name]"
+        ].join("\n");
+    }
+    if (error.code === "UNKNOWN_PATH_ALIAS") {
+        const details = readDetailsObject(error.details);
+        const alias = readString(details.alias);
+        const available = Array.isArray(details.available)
+            ? details.available.filter((item) => typeof item === "string")
+            : [];
+        return [
+            `unknown AIB path alias: @${alias ?? ""}`,
+            "",
+            available.length > 0
+                ? `Available aliases: ${available.map((item) => `@${item}`).join(", ")}`
+                : "No AIB path aliases are configured.",
+            ...(available.length > 0
+                ? ["Run:", "aib sync"]
+                : ["Check config:", "aib config", "or run:", "aib sync"])
+        ].join("\n");
+    }
+    return null;
+}
+function formatAmbiguousEntitySelectorText(error) {
+    const details = readDetailsObject(error.details);
+    const ambiguities = Array.isArray(details.ambiguities)
+        ? details.ambiguities.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item))
+        : [];
+    if (ambiguities.length > 0) {
+        const entities = ambiguities
+            .map((item) => readString(item.entity))
+            .filter((item) => item !== null);
+        const lines = [
+            entities.length === 1
+                ? `ambiguous entity: ${entities[0]}`
+                : `ambiguous entities: ${entities.join(", ")}`,
+            "",
+            "Use available:"
+        ];
+        for (const item of ambiguities) {
+            const suggestions = Array.isArray(item.suggestions)
+                ? item.suggestions.filter((suggestion) => typeof suggestion === "string" && suggestion.length > 0)
+                : [];
+            if (suggestions.length > 0) {
+                lines.push(`- ${suggestions.join(", ")}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    const suggestions = Array.isArray(details.suggestions)
+        ? details.suggestions.filter((suggestion) => typeof suggestion === "string" && suggestion.length > 0)
+        : [];
+    return [
+        error.message,
+        ...(suggestions.length > 0 ? ["", "Use available:", `- ${suggestions.join(", ")}`] : [])
+    ].join("\n");
+}
+function formatConfigErrorText(error) {
+    const lines = [
+        "aib config invalid",
+        "",
+        error.message
+    ];
+    if (error.code === "INVALID_PATH_ALIAS_NAME") {
+        lines.push("Use alias names without @, for example:", `"pathAliases": {`, `  "svc": "src/services"`, `}`);
+    }
+    if (error.code === "RESERVED_PATH_ALIAS_NAME") {
+        const details = readDetailsObject(error.details);
+        const reserved = Array.isArray(details.reserved)
+            ? details.reserved.filter((item) => typeof item === "string")
+            : [];
+        if (reserved.length > 0) {
+            lines.push(`Reserved aliases: ${reserved.join(", ")}`);
+        }
+    }
+    lines.push("", "Edit aib.json, then run:", "aib sync");
+    return lines.join("\n");
+}
+function readDetailsObject(details) {
+    return details && typeof details === "object" && !Array.isArray(details)
+        ? details
+        : {};
+}
+function readString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/shared/event-loop.js

@@ -1 +1,6 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.yieldToEventLoop=t;async function t(){await new Promise(e=>setImmediate(e))}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yieldToEventLoop = yieldToEventLoop;
+async function yieldToEventLoop() {
+    await new Promise((resolve) => setImmediate(resolve));
+}

package/dist/shared/hints.js

@@ -1 +1,37 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.commandHint=e,exports.actionHint=i,exports.docsHint=a,exports.configHint=c,exports.buildUpgradeExtensionHints=s;function e(n,t){return{kind:"command",command:n,description:t}}function i(n){return{kind:"action",description:n}}function a(n,t){return{kind:"docs",path:n,description:t}}function c(n,t,o){const r={kind:"config",name:n,description:t};return o!==void 0&&(r.value=o),r}function s(){return[i("Install a newer extension VSIX that supports the requested operation."),e("npm --prefix packages/extension run package:vsix","Build a fresh local VSIX artifact."),i("Reload the IDE window after installing the latest extension."),e("aib listInstances","Check which IDE instances are currently registered.")]}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandHint = commandHint;
+exports.actionHint = actionHint;
+exports.docsHint = docsHint;
+exports.configHint = configHint;
+function commandHint(command, description) {
+    return {
+        kind: "command",
+        command,
+        description
+    };
+}
+function actionHint(description) {
+    return {
+        kind: "action",
+        description
+    };
+}
+function docsHint(path, description) {
+    return {
+        kind: "docs",
+        path,
+        description
+    };
+}
+function configHint(name, description, value) {
+    const hint = {
+        kind: "config",
+        name,
+        description
+    };
+    if (value !== undefined) {
+        hint.value = value;
+    }
+    return hint;
+}