@zenalexa/unicli 0.209.0 → 0.211.2

package/dist/discovery/search.d.ts

@@ -0,0 +1,73 @@
+/**
+ * BM25-based bilingual search engine for command discovery.
+ *
+ * Replaces the naive `String.includes()` filter with a proper information
+ * retrieval algorithm. Designed for ~1000 commands across ~200 sites.
+ *
+ * Architecture:
+ *   1. Build-time: `scripts/build-manifest.js` generates the inverted index
+ *      and IDF values, shipped as `dist/manifest-search.json`.
+ *   2. Runtime: this module loads the index lazily on first search call,
+ *      then scores queries using BM25 with bilingual keyword expansion.
+ *
+ * Performance: <10ms for 1000 documents on a cold index load. The inverted
+ * index is ~50KB — small enough to hold in memory permanently.
+ */
+export interface SearchResult {
+    site: string;
+    command: string;
+    description: string;
+    score: number;
+    usage: string;
+    category: string;
+}
+/** Serialized search index (generated at build time, loaded at runtime). */
+export interface SearchIndex {
+    /** Mapping: term → list of document indices that contain this term */
+    postings: Record<string, number[]>;
+    /** IDF (Inverse Document Frequency) for each term */
+    idf: Record<string, number>;
+    /** All documents with their metadata */
+    documents: Array<{
+        id: string;
+        site: string;
+        command: string;
+        description: string;
+        terms: string[];
+    }>;
+    /** Average document length (term count) across the corpus */
+    avgDl: number;
+    /** Total document count */
+    N: number;
+}
+/**
+ * Build a search index from a manifest object.
+ * Exported for use by the build script.
+ */
+export declare function buildIndex(manifest: {
+    sites: Record<string, {
+        commands: Array<{
+            name: string;
+            description: string;
+        }>;
+    }>;
+}): SearchIndex;
+/**
+ * Search all commands by natural language query.
+ *
+ * Algorithm:
+ *   1. Tokenize query (bilingual-aware)
+ *   2. Expand tokens via alias table
+ *   3. Compute BM25 base score for each candidate document
+ *   4. Apply boost signals (site match, command match, category match)
+ *   5. Return top-K results with usage examples
+ *
+ * @param query - Natural language query (Chinese or English)
+ * @param limit - Maximum results to return (default 5)
+ */
+export declare function search(query: string, limit?: number): SearchResult[];
+/**
+ * Force-reload the search index (useful after index rebuild).
+ */
+export declare function invalidateCache(): void;
+//# sourceMappingURL=search.d.ts.map

package/dist/discovery/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/discovery/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAcD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,wCAAwC;IACxC,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAC;CACX;AAkFD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,MAAM,CACX,MAAM,EACN;QAAE,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAC3D,CAAC;CACH,GAAG,WAAW,CAsDd;AAoID;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,YAAY,EAAE,CA0G/D;AASD;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/discovery/search.js

@@ -0,0 +1,355 @@
+/**
+ * BM25-based bilingual search engine for command discovery.
+ *
+ * Replaces the naive `String.includes()` filter with a proper information
+ * retrieval algorithm. Designed for ~1000 commands across ~200 sites.
+ *
+ * Architecture:
+ *   1. Build-time: `scripts/build-manifest.js` generates the inverted index
+ *      and IDF values, shipped as `dist/manifest-search.json`.
+ *   2. Runtime: this module loads the index lazily on first search call,
+ *      then scores queries using BM25 with bilingual keyword expansion.
+ *
+ * Performance: <10ms for 1000 documents on a cold index load. The inverted
+ * index is ~50KB — small enough to hold in memory permanently.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expandToken, tokenizeQuery, SITE_ALIASES, SITE_CATEGORIES, CATEGORY_ALIASES, } from "./aliases.js";
+// ── BM25 Parameters ─────────────────────────────────────────────────────────
+// Standard BM25 tuning. k1 controls term frequency saturation,
+// b controls document length normalization.
+const K1 = 1.2;
+const B = 0.75;
+// ── Hybrid Scoring ──────────────────────────────────────────────────────────
+// StackOne benchmark (Feb 2026, 2700 test cases, 270 tools) found:
+//   Pure BM25 Top-1: 14%
+//   BM25+TF-IDF 20/80 blend Top-1: 21%
+//   Embedding Top-1: 38%
+// We use the 20/80 blend as the base, with domain-specific boosts on top.
+const ALPHA_BM25 = 0.2;
+const ALPHA_TFIDF = 0.8;
+// ── Score Boost Weights ─────────────────────────────────────────────────────
+// Applied on top of the hybrid BM25+TF-IDF base score.
+const BOOST_SITE_EXACT = 15.0; // Query token exactly matches site name
+const BOOST_SITE_ALIAS = 12.0; // Query token's alias matches site name
+const BOOST_CMD_EXACT = 8.0; // Query token exactly matches command name
+const BOOST_CMD_PARTIAL = 3.0; // Query token is substring of command name
+const BOOST_CATEGORY = 2.0; // Query token matches site's category
+// ── Index Management ────────────────────────────────────────────────────────
+let cachedIndex = null;
+/**
+ * Resolve the path to the pre-built search index.
+ * Falls back to building one on-the-fly from the manifest if the
+ * pre-built index doesn't exist.
+ */
+function getIndexPath() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    return join(__dirname, "..", "..", "dist", "manifest-search.json");
+}
+/**
+ * Load or build the search index. Called lazily on first search.
+ */
+function loadIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const indexPath = getIndexPath();
+    if (existsSync(indexPath)) {
+        cachedIndex = JSON.parse(readFileSync(indexPath, "utf-8"));
+        return cachedIndex;
+    }
+    // Fallback: build index on-the-fly from manifest.json
+    cachedIndex = buildIndexFromManifest();
+    return cachedIndex;
+}
+/**
+ * Build a search index from the manifest.json file.
+ * Used when the pre-built search index doesn't exist (dev mode).
+ */
+function buildIndexFromManifest() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const manifestPath = join(__dirname, "..", "..", "dist", "manifest.json");
+    if (!existsSync(manifestPath)) {
+        // No manifest either — return empty index
+        return { postings: {}, idf: {}, documents: [], avgDl: 0, N: 0 };
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    return buildIndex(manifest);
+}
+/**
+ * Build a search index from a manifest object.
+ * Exported for use by the build script.
+ */
+export function buildIndex(manifest) {
+    const documents = [];
+    for (const [site, info] of Object.entries(manifest.sites)) {
+        for (const cmd of info.commands) {
+            const terms = tokenizeDocument(site, cmd.name, cmd.description ?? "");
+            documents.push({
+                id: `${site}/${cmd.name}`,
+                site,
+                command: cmd.name,
+                description: cmd.description ?? "",
+                terms,
+                termCount: terms.length,
+            });
+        }
+    }
+    const N = documents.length;
+    const avgDl = N > 0 ? documents.reduce((sum, d) => sum + d.termCount, 0) / N : 0;
+    // Build inverted index
+    const postings = {};
+    for (let i = 0; i < documents.length; i++) {
+        const seen = new Set();
+        for (const term of documents[i].terms) {
+            if (seen.has(term))
+                continue;
+            seen.add(term);
+            if (!postings[term])
+                postings[term] = [];
+            postings[term].push(i);
+        }
+    }
+    // Compute IDF for each term
+    const idf = {};
+    for (const [term, docs] of Object.entries(postings)) {
+        // BM25 IDF: log((N - df + 0.5) / (df + 0.5) + 1)
+        const df = docs.length;
+        idf[term] = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+    }
+    return {
+        postings,
+        idf,
+        documents: documents.map((d) => ({
+            id: d.id,
+            site: d.site,
+            command: d.command,
+            description: d.description,
+            terms: d.terms,
+        })),
+        avgDl,
+        N,
+    };
+}
+/**
+ * Tokenize a document (site + command + description) into search terms.
+ * Produces lowercase terms, splits on hyphens and underscores.
+ */
+function tokenizeDocument(site, command, description) {
+    const terms = [];
+    // Site name and its parts
+    const siteParts = site.toLowerCase().split(/[-_]/);
+    terms.push(site.toLowerCase(), ...siteParts);
+    // Command name and its parts
+    const cmdParts = command.toLowerCase().split(/[-_]/);
+    terms.push(command.toLowerCase(), ...cmdParts);
+    // Description words (lowercase, filter short words)
+    const descWords = description
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fff\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 1);
+    terms.push(...descWords);
+    // Category as a term
+    const category = SITE_CATEGORIES.get(site);
+    if (category)
+        terms.push(category);
+    return terms;
+}
+// ── BM25 Scoring ────────────────────────────────────────────────────────────
+/**
+ * Compute BM25 score for a single document given query terms.
+ */
+function bm25Score(docTerms, docLength, queryTerms, index) {
+    let score = 0;
+    // Count term frequencies in this document
+    const tf = new Map();
+    for (const term of docTerms) {
+        tf.set(term, (tf.get(term) ?? 0) + 1);
+    }
+    for (const qt of queryTerms) {
+        const termIdf = index.idf[qt];
+        if (termIdf === undefined)
+            continue; // term not in corpus
+        const termTf = tf.get(qt) ?? 0;
+        if (termTf === 0)
+            continue;
+        // BM25 TF component: (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * dl/avgdl))
+        const numerator = termTf * (K1 + 1);
+        const denominator = termTf + K1 * (1 - B + B * (docLength / index.avgDl));
+        score += termIdf * (numerator / denominator);
+    }
+    return score;
+}
+// ── TF-IDF Cosine Similarity ────────────────────────────────────────────────
+/**
+ * Compute TF-IDF cosine similarity between a query and a document.
+ *
+ * TF-IDF for a term t in document d:
+ *   tf(t,d) = count(t in d) / |d|
+ *   tfidf(t,d) = tf(t,d) * idf(t)
+ *
+ * Cosine similarity = dot(query_vec, doc_vec) / (|query_vec| * |doc_vec|)
+ */
+function tfidfCosine(docTerms, queryTerms, index) {
+    const docLen = docTerms.length;
+    if (docLen === 0)
+        return 0;
+    // Build full doc TF map
+    const docTf = new Map();
+    for (const term of docTerms) {
+        docTf.set(term, (docTf.get(term) ?? 0) + 1);
+    }
+    // Compute full document norm (all terms, not just query overlap)
+    let docNormSq = 0;
+    for (const [term, count] of docTf) {
+        const idfVal = index.idf[term];
+        if (idfVal === undefined)
+            continue;
+        const w = (count / docLen) * idfVal;
+        docNormSq += w * w;
+    }
+    // Compute query norm and dot product
+    let dotProduct = 0;
+    let queryNormSq = 0;
+    for (const qt of queryTerms) {
+        const idfVal = index.idf[qt];
+        if (idfVal === undefined)
+            continue;
+        // Query TF-IDF: binary tf (1) × idf
+        const queryWeight = idfVal;
+        queryNormSq += queryWeight * queryWeight;
+        // Doc TF-IDF: normalized tf × idf
+        const rawTf = docTf.get(qt) ?? 0;
+        if (rawTf === 0)
+            continue;
+        const docWeight = (rawTf / docLen) * idfVal;
+        dotProduct += queryWeight * docWeight;
+    }
+    const normProduct = Math.sqrt(queryNormSq) * Math.sqrt(docNormSq);
+    if (normProduct === 0)
+        return 0;
+    return dotProduct / normProduct;
+}
+// ── Main Search Function ────────────────────────────────────────────────────
+/**
+ * Search all commands by natural language query.
+ *
+ * Algorithm:
+ *   1. Tokenize query (bilingual-aware)
+ *   2. Expand tokens via alias table
+ *   3. Compute BM25 base score for each candidate document
+ *   4. Apply boost signals (site match, command match, category match)
+ *   5. Return top-K results with usage examples
+ *
+ * @param query - Natural language query (Chinese or English)
+ * @param limit - Maximum results to return (default 5)
+ */
+export function search(query, limit = 5) {
+    const index = loadIndex();
+    if (index.N === 0)
+        return [];
+    // Step 1: Tokenize
+    const rawTokens = tokenizeQuery(query);
+    // Step 2: Expand via aliases
+    const expandedTerms = [];
+    const siteHints = []; // Directly matched site names
+    const categoryHints = []; // Matched categories
+    for (const token of rawTokens) {
+        const expanded = expandToken(token);
+        expandedTerms.push(...expanded);
+        // Check if this token resolves to a site name
+        const siteMatch = SITE_ALIASES.get(token) ?? SITE_ALIASES.get(token.toLowerCase());
+        if (siteMatch)
+            siteHints.push(siteMatch);
+        // Check if this token is directly a known site
+        if (index.documents.some((d) => d.site === token.toLowerCase())) {
+            siteHints.push(token.toLowerCase());
+        }
+        // Check category alias
+        const catMatch = CATEGORY_ALIASES.get(token) ?? CATEGORY_ALIASES.get(token.toLowerCase());
+        if (catMatch)
+            categoryHints.push(catMatch);
+    }
+    const queryTerms = [...new Set(expandedTerms.map((t) => t.toLowerCase()))];
+    // Step 3: Find candidate documents (union of posting lists)
+    const candidateSet = new Set();
+    for (const qt of queryTerms) {
+        const postings = index.postings[qt];
+        if (postings) {
+            for (const docIdx of postings) {
+                candidateSet.add(docIdx);
+            }
+        }
+    }
+    // If site hints exist, also add ALL commands for those sites
+    if (siteHints.length > 0) {
+        for (let i = 0; i < index.documents.length; i++) {
+            if (siteHints.includes(index.documents[i].site)) {
+                candidateSet.add(i);
+            }
+        }
+    }
+    if (candidateSet.size === 0)
+        return [];
+    // Step 4: Score candidates using hybrid BM25 + TF-IDF
+    const scored = [];
+    for (const idx of candidateSet) {
+        const doc = index.documents[idx];
+        // Hybrid base: alpha-blend BM25 and TF-IDF cosine similarity.
+        // BM25 scores are unbounded; cosine is [0,1]. We scale cosine by the
+        // average BM25 score across candidates to keep the blend balanced.
+        const bm25 = bm25Score(doc.terms, doc.terms.length, queryTerms, index);
+        const tfidf = tfidfCosine(doc.terms, queryTerms, index);
+        let score = ALPHA_BM25 * bm25 + ALPHA_TFIDF * tfidf * 10;
+        // Boost: exact site name match
+        if (siteHints.includes(doc.site)) {
+            score += BOOST_SITE_EXACT;
+        }
+        // Boost: alias-resolved site match
+        for (const qt of queryTerms) {
+            if (qt === doc.site)
+                score += BOOST_SITE_ALIAS;
+            if (qt === doc.command)
+                score += BOOST_CMD_EXACT;
+            if (doc.command.includes(qt) && qt.length > 2)
+                score += BOOST_CMD_PARTIAL;
+        }
+        // Boost: category match
+        const docCategory = SITE_CATEGORIES.get(doc.site);
+        if (docCategory && categoryHints.includes(docCategory)) {
+            score += BOOST_CATEGORY;
+        }
+        if (score > 0)
+            scored.push({ idx, score });
+    }
+    // Step 5: Sort and return top-K
+    scored.sort((a, b) => b.score - a.score);
+    const topK = scored.slice(0, limit);
+    return topK.map(({ idx, score }) => {
+        const doc = index.documents[idx];
+        const category = SITE_CATEGORIES.get(doc.site) ?? "other";
+        return {
+            site: doc.site,
+            command: doc.command,
+            description: doc.description,
+            score: Math.round(score * 100) / 100,
+            usage: buildUsageExample(doc.site, doc.command),
+            category,
+        };
+    });
+}
+/**
+ * Build a usage example string for a command.
+ */
+function buildUsageExample(site, command) {
+    return `unicli ${site} ${command}`;
+}
+/**
+ * Force-reload the search index (useful after index rebuild).
+ */
+export function invalidateCache() {
+    cachedIndex = null;
+}
+//# sourceMappingURL=search.js.map

package/dist/discovery/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/discovery/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,WAAW,EACX,aAAa,EACb,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,cAAc,CAAC;AA6CtB,+EAA+E;AAC/E,+DAA+D;AAC/D,4CAA4C;AAE5C,MAAM,EAAE,GAAG,GAAG,CAAC;AACf,MAAM,CAAC,GAAG,IAAI,CAAC;AAEf,+EAA+E;AAC/E,mEAAmE;AACnE,yBAAyB;AACzB,uCAAuC;AACvC,yBAAyB;AACzB,0EAA0E;AAE1E,MAAM,UAAU,GAAG,GAAG,CAAC;AACvB,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,+EAA+E;AAC/E,uDAAuD;AAEvD,MAAM,gBAAgB,GAAG,IAAI,CAAC,CAAC,wCAAwC;AACvE,MAAM,gBAAgB,GAAG,IAAI,CAAC,CAAC,wCAAwC;AACvE,MAAM,eAAe,GAAG,GAAG,CAAC,CAAC,2CAA2C;AACxE,MAAM,iBAAiB,GAAG,GAAG,CAAC,CAAC,2CAA2C;AAC1E,MAAM,cAAc,GAAG,GAAG,CAAC,CAAC,sCAAsC;AAElE,+EAA+E;AAE/E,IAAI,WAAW,GAAuB,IAAI,CAAC;AAE3C;;;;GAIG;AACH,SAAS,YAAY;IACnB,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC;AACrE,CAAC;AAED;;GAEG;AACH,SAAS,SAAS;IAChB,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IAEpC,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAgB,CAAC;QAC1E,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,sDAAsD;IACtD,WAAW,GAAG,sBAAsB,EAAE,CAAC;IACvC,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,SAAS,sBAAsB;IAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;IAE1E,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,0CAA0C;QAC1C,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAClE,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAK9D,CAAC;IAEF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,QAK1B;IACC,MAAM,SAAS,GAAe,EAAE,CAAC;IAEjC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1D,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;YACtE,SAAS,CAAC,IAAI,CAAC;gBACb,EAAE,EAAE,GAAG,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE;gBACzB,IAAI;gBACJ,OAAO,EAAE,GAAG,CAAC,IAAI;gBACjB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;gBAClC,KAAK;gBACL,SAAS,EAAE,KAAK,CAAC,MAAM;aACxB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;IAC3B,MAAM,KAAK,GACT,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAErE,uBAAuB;IACvB,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC7B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,iDAAiD;QACjD,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACvB,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO;QACL,QAAQ;QACR,GAAG;QACH,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC/B,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,KAAK,EAAE,CAAC,CAAC,KAAK;SACf,CAAC,CAAC;QACH,KAAK;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CACvB,IAAY,EACZ,OAAe,EACf,WAAmB;IAEnB,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,0BAA0B;IAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,SAAS,CAAC,CAAC;IAE7C,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC;IAE/C,oDAAoD;IACpD,MAAM,SAAS,GAAG,WAAW;SAC1B,WAAW,EAAE;SACb,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC;SACzC,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC;IAEzB,qBAAqB;IACrB,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEnC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAE/E;;GAEG;AACH,SAAS,SAAS,CAChB,QAAkB,EAClB,SAAiB,EACjB,UAAoB,EACpB,KAAkB;IAElB,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,0CAA0C;IAC1C,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS,CAAC,qBAAqB;QAE1D,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,CAAC;YAAE,SAAS;QAE3B,0EAA0E;QAC1E,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACpC,MAAM,WAAW,GAAG,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1E,KAAK,IAAI,OAAO,GAAG,CAAC,SAAS,GAAG,WAAW,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,SAAS,WAAW,CAClB,QAAkB,EAClB,UAAoB,EACpB,KAAkB;IAElB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC/B,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE3B,wBAAwB;IACxB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,iEAAiE;IACjE,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;QACpC,SAAS,IAAI,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,qCAAqC;IACrC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QAEnC,oCAAoC;QACpC,MAAM,WAAW,GAAG,MAAM,CAAC;QAC3B,WAAW,IAAI,WAAW,GAAG,WAAW,CAAC;QAEzC,kCAAkC;QAClC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,CAAC;YAAE,SAAS;QAC1B,MAAM,SAAS,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;QAC5C,UAAU,IAAI,WAAW,GAAG,SAAS,CAAC;IACxC,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAClE,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEhC,OAAO,UAAU,GAAG,WAAW,CAAC;AAClC,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,KAAK,GAAG,CAAC;IAC7C,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;IAC1B,IAAI,KAAK,CAAC,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE7B,mBAAmB;IACnB,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEvC,6BAA6B;IAC7B,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,MAAM,SAAS,GAAa,EAAE,CAAC,CAAC,8BAA8B;IAC9D,MAAM,aAAa,GAAa,EAAE,CAAC,CAAC,qBAAqB;IAEzD,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACpC,aAAa,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QAEhC,8CAA8C;QAC9C,MAAM,SAAS,GACb,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACnE,IAAI,SAAS;YAAE,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAEzC,+CAA+C;QAC/C,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAChE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACtC,CAAC;QAED,uBAAuB;QACvB,MAAM,QAAQ,GACZ,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3E,IAAI,QAAQ;YAAE,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;IAE3E,4DAA4D;IAC5D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChD,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,sDAAsD;IACtD,MAAM,MAAM,GAA0C,EAAE,CAAC;IAEzD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAEjC,8DAA8D;QAC9D,qEAAqE;QACrE,mEAAmE;QACnE,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;QACvE,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;QACxD,IAAI,KAAK,GAAG,UAAU,GAAG,IAAI,GAAG,WAAW,GAAG,KAAK,GAAG,EAAE,CAAC;QAEzD,+BAA+B;QAC/B,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,KAAK,IAAI,gBAAgB,CAAC;QAC5B,CAAC;QAED,mCAAmC;QACnC,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;YAC5B,IAAI,EAAE,KAAK,GAAG,CAAC,IAAI;gBAAE,KAAK,IAAI,gBAAgB,CAAC;YAC/C,IAAI,EAAE,KAAK,GAAG,CAAC,OAAO;gBAAE,KAAK,IAAI,eAAe,CAAC;YACjD,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;gBAAE,KAAK,IAAI,iBAAiB,CAAC;QAC5E,CAAC;QAED,wBAAwB;QACxB,MAAM,WAAW,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,WAAW,IAAI,aAAa,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YACvD,KAAK,IAAI,cAAc,CAAC;QAC1B,CAAC;QAED,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,gCAAgC;IAChC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAEpC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC;QAC1D,OAAO;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG;YACpC,KAAK,EAAE,iBAAiB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC;YAC/C,QAAQ;SACT,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,IAAY,EAAE,OAAe;IACtD,OAAO,UAAU,IAAI,IAAI,OAAO,EAAE,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC"}

package/dist/engine/yaml-runner.d.ts

@@ -45,6 +45,10 @@ export declare class PipelineError extends Error {
         statusCode?: number;
         responsePreview?: string;
         suggestion: string;
+        /** true for transient failures (timeout, 429, 5xx), false for permanent (404, auth, config) */
+        retryable?: boolean;
+        /** Fallback commands the agent can try when this command fails */
+        alternatives?: string[];
     };
     constructor(message: string, detail: {
         step: number;
@@ -55,9 +59,15 @@ export declare class PipelineError extends Error {
         statusCode?: number;
         responsePreview?: string;
         suggestion: string;
+        /** true for transient failures (timeout, 429, 5xx), false for permanent (404, auth, config) */
+        retryable?: boolean;
+        /** Fallback commands the agent can try when this command fails */
+        alternatives?: string[];
     });
     /** JSON output for AI agents — includes everything needed to self-repair */
     toAgentJSON(adapterPath?: string): {
+        retryable: boolean;
+        alternatives: string[];
         step: number;
         action: string;
         config: unknown;

package/dist/engine/yaml-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-runner.d.ts","sourceRoot":"","sources":["../../src/engine/yaml-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAmBtD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAGpB,MAAM,EAAE;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,EACL,YAAY,GACZ,eAAe,GACf,cAAc,GACd,aAAa,GACb,SAAS,GACT,kBAAkB,GAClB,kBAAkB,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;KACpB;gBAjBD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,EACL,YAAY,GACZ,eAAe,GACf,cAAc,GACd,aAAa,GACb,SAAS,GACT,kBAAkB,GAClB,kBAAkB,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;KACpB;IAMH,4EAA4E;IAC5E,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM;cAtBtB,MAAM;gBACJ,MAAM;gBACN,OAAO;mBAEX,YAAY,GACZ,eAAe,GACf,cAAc,GACd,aAAa,GACb,SAAS,GACT,kBAAkB,GAClB,kBAAkB;cAChB,MAAM;qBACC,MAAM;0BACD,MAAM;oBACZ,MAAM;;;;CAevB;AAmID,wBAAsB,WAAW,CAC/B,KAAK,EAAE,YAAY,EAAE,EACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC,CAqPpB;AA+wBD,iBAAS,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBjE;AAwOD;;;;;GAKG;AACH,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAyFjE,CAAC;AA0GF;;;;;;;GAOG;AACH,iBAAS,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CA6D7E;AAqwBD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"yaml-runner.d.ts","sourceRoot":"","sources":["../../src/engine/yaml-runner.ts"],"names":[],"mappings":"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"}

package/dist/engine/yaml-runner.js

@@ -49,6 +49,8 @@ export class PipelineError extends Error {
             error: this.message,
             adapter: adapterPath,
             ...this.detail,
+            retryable: this.detail.retryable ?? false,
+            alternatives: this.detail.alternatives ?? [],
         };
     }
 }
@@ -170,6 +172,8 @@ export async function runPipeline(steps, args, base, options) {
                 config: { site: options.site, strategy: options.strategy },
                 errorType: "http_error",
                 suggestion: `Either start Chrome with "unicli browser start" and login to ${options.site}, or create cookie file at ~/.unicli/cookies/${options.site}.json`,
+                retryable: false,
+                alternatives: [`unicli auth setup ${options.site}`],
             });
         }
         cookieHeader = formatCookieHeader(cookies);
@@ -353,12 +357,16 @@ export async function runPipeline(steps, args, base, options) {
                 }
                 if (err instanceof PipelineError)
                     throw err;
-                throw new PipelineError(`Step ${i} (${action}) failed: ${err instanceof Error ? err.message : String(err)}`, {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                const isTransient = /timeout|ETIMEDOUT|ECONNREFUSED|ECONNRESET|socket hang up/i.test(errMsg);
+                throw new PipelineError(`Step ${i} (${action}) failed: ${errMsg}`, {
                     step: i,
                     action,
                     config,
-                    errorType: "parse_error",
+                    errorType: isTransient ? "timeout" : "parse_error",
                     suggestion: `Check the ${action} step at index ${i} in the adapter YAML. The expression or configuration may be invalid.`,
+                    retryable: isTransient,
+                    alternatives: [],
                 });
             }
             if (ctx.tempDir)
@@ -468,6 +476,8 @@ function assertionError(message, config, stepIndex) {
         config,
         errorType: "assertion_failed",
         suggestion: "Check the assertion conditions in the adapter YAML. The page state may not match expectations.",
+        retryable: false,
+        alternatives: [],
     });
 }
 async function stepFetch(ctx, config) {
@@ -619,6 +629,10 @@ async function fetchJson(url, config, cookieHeader) {
         catch {
             /* ignore */
         }
+        const isRetryableStatus = resp.status === 429 ||
+            resp.status === 500 ||
+            resp.status === 502 ||
+            resp.status === 503;
         throw new PipelineError(`HTTP ${resp.status} ${resp.statusText} from ${url}`, {
             step: -1, // will be overwritten by caller
             action: "fetch",
@@ -634,6 +648,10 @@ async function fetchJson(url, config, cookieHeader) {
                     : resp.status === 429
                         ? "Rate limited. Add a delay between requests or reduce the limit parameter."
                         : `HTTP ${resp.status} error. Check if the API endpoint is still valid.`,
+            retryable: isRetryableStatus,
+            alternatives: resp.status === 401 || resp.status === 403
+                ? ["unicli auth setup <site>"]
+                : [],
         });
     }
     // Unreachable — loop always returns or throws — but satisfies TypeScript
@@ -649,6 +667,8 @@ function stepSelect(ctx, path, stepIndex) {
             config: path,
             errorType: "selector_miss",
             suggestion: `The path "${resolved}" does not exist in the API response. Inspect the actual response JSON to find the correct path, then update the "select" step in the adapter YAML.`,
+            retryable: false,
+            alternatives: [],
         });
     }
     return { ...ctx, data };
@@ -725,6 +745,13 @@ async function stepFetchText(ctx, config) {
             url,
             statusCode: resp.status,
             suggestion: `Check if the URL is still valid: ${url}`,
+            retryable: resp.status === 429 ||
+                resp.status === 500 ||
+                resp.status === 502 ||
+                resp.status === 503,
+            alternatives: resp.status === 401 || resp.status === 403
+                ? ["unicli auth setup <site>"]
+                : [],
         });
     }
     const text = await resp.text();
@@ -837,6 +864,8 @@ async function stepExec(ctx, config) {
                 },
                 errorType: "assertion_failed",
                 suggestion: denial.hint,
+                retryable: false,
+                alternatives: [],
             });
         }
     }
@@ -910,6 +939,8 @@ async function stepExec(ctx, config) {
                     config: { command: cmd, args: execArgs },
                     errorType: "parse_error",
                     suggestion: `Check that the command writes to "${outputFile}". Verify the path is correct.`,
+                    retryable: false,
+                    alternatives: [],
                 });
             }
         }
@@ -951,12 +982,15 @@ async function stepExec(ctx, config) {
         if (err instanceof PipelineError)
             throw err;
         const msg = err instanceof Error ? err.message : String(err);
+        const isExecTransient = /timeout|ETIMEDOUT|ECONNREFUSED|ECONNRESET/i.test(msg);
         throw new PipelineError(`exec "${cmd}" failed: ${msg}`, {
             step: -1,
             action: "exec",
             config: { command: cmd, args: execArgs },
-            errorType: "parse_error",
+            errorType: isExecTransient ? "timeout" : "parse_error",
             suggestion: `Check that "${cmd}" is installed and accessible. Run: which ${cmd}`,
+            retryable: isExecTransient,
+            alternatives: [],
         });
     }
 }
@@ -1043,6 +1077,8 @@ async function stepIf(ctx, config, stepIndex, depth = 0) {
             config,
             errorType: "parse_error",
             suggestion: "Reduce nesting depth of if/else steps. Maximum is 10 levels.",
+            retryable: false,
+            alternatives: [],
         });
     }
     const conditionStr = typeof config.if === "string" ? config.if : String(config.if);
@@ -1069,6 +1105,8 @@ async function stepEach(ctx, config, stepIndex, depth) {
             config,
             errorType: "parse_error",
             suggestion: "Reduce nesting depth of loop steps. Maximum is 10 levels.",
+            retryable: false,
+            alternatives: [],
         });
     }
     const maxIterations = Math.max(config.max ?? 100, 1);
@@ -1111,6 +1149,8 @@ async function stepParallel(ctx, branches, merge, stepIndex, depth) {
             config: branches,
             errorType: "parse_error",
             suggestion: "Reduce nesting depth of parallel steps. Maximum is 10 levels.",
+            retryable: false,
+            alternatives: [],
         });
     }
     const results = await Promise.all(branches.map(async (branch) => {
@@ -1597,6 +1637,8 @@ async function stepClick(ctx, config) {
         config,
         errorType: "expression_error",
         suggestion: 'Provide either a CSS selector string, {selector: "..."}, or {x: N, y: N} for coordinate click.',
+        retryable: false,
+        alternatives: [],
     });
 }
 async function stepType(ctx, config) {
@@ -1675,6 +1717,8 @@ async function stepIntercept(ctx, config) {
             config: { capture: capturePattern, trigger },
             errorType: "timeout",
             suggestion: `No network request matching "${capturePattern}" was observed. Verify the capture pattern matches the target API URL and that the trigger action causes the request.`,
+            retryable: true,
+            alternatives: [],
         });
     }
     // Apply optional dot-path selector to captured data
@@ -1760,6 +1804,8 @@ async function stepTap(ctx, config) {
             config,
             errorType: "expression_error",
             suggestion: "Store name must be a valid JavaScript identifier.",
+            retryable: false,
+            alternatives: [],
         });
     }
     if (!/^[a-zA-Z_$][\w$]*$/.test(actionName)) {
@@ -1769,6 +1815,8 @@ async function stepTap(ctx, config) {
             config,
             errorType: "expression_error",
             suggestion: "Action name must be a valid JavaScript identifier.",
+            retryable: false,
+            alternatives: [],
         });
     }
     const framework = config.framework ?? "auto";