@molecule/api-ai-tools 1.8.1 → 1.8.2

package/dist/command-position.d.ts

@@ -58,6 +58,48 @@ export declare function durationSeconds(word: string): number | null;
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export declare function commandSegments(command: string): CommandSegment[];
+/**
+ * One statement of a shell command, with where it sits and the variables it sets for itself.
+ *
+ * `commandSegments` answers WHAT runs; this answers where, and what the shell binds to it — the
+ * two things a caller that WRITES into a command needs. The platform composes a run from the
+ * executor's own command in more than one place, and a value written for the runner belongs in
+ * the runner's own statement: `APP_BASE=https://… cd app && npx playwright test` sets the variable
+ * for `cd` alone, so the Playwright config falls back to the local app while the command line
+ * still names the deployed host (xr-molecule-flash-m103 +28:08).
+ */
+export interface LocatedCommandSegment {
+    /**
+     * What the statement runs, or null when it only sets variables (`BASE=http://…` on its own):
+     * that shape persists in the shell, so a caller following assignments across `;`/`&&` has to
+     * see it.
+     */
+    segment: CommandSegment | null;
+    /** The statement's own leading `NAME=value` words, as written (`TEST_MODE=fullstack`). */
+    assignments: readonly string[];
+    /**
+     * The offset in the command of the statement's first word, or null for a segment inside a
+     * nested `sh -c '<command>'` string — its positions are offsets in THAT string, not in this
+     * command, so nothing may be spliced at them.
+     */
+    start: number | null;
+    /**
+     * The offset in the command just before the word the statement runs — after its own leading
+     * `NAME=value` words and their whitespace. A `NAME=value` written here is in the environment of
+     * the program the statement runs (`… TEST_MODE=fullstack <here>npx playwright test`). Null
+     * inside a nested `sh -c` string, for the same reason as {@link start}.
+     */
+    assignmentOffset: number | null;
+}
+/**
+ * Every statement of a command, with its own assignments and where it sits — assignment-only
+ * statements included, because the variables those persist are exactly what a later statement of
+ * the same command reads.
+ *
+ * @param command - The shell command.
+ * @returns One entry per statement or pipeline stage, in order.
+ */
+export declare function locatedCommandSegments(command: string): LocatedCommandSegment[];
 /**
  * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
  * under (`timeout 280 hurl --test …` → 280), or null when it carries none.

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAuSD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAkVD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAqDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -400,11 +400,14 @@ function commandStart(words) {
  * no runner, and every run of it reads as nothing).
  *
  * @param command - The shell command.
- * @returns Each segment's text, in order, with empty ones dropped.
+ * @returns Each segment's text and the offset in the command its first character sits at, in
+ *   order, with empty ones dropped.
  */
 function splitSegments(command) {
     const parts = [];
     let buffer = '';
+    /** The offset in the command of the current buffer's first character. */
+    let bufferStart = 0;
     /** The nestings this position sits inside, outermost first. */
     const stack = [];
     for (let i = 0; i < command.length; i++) {
@@ -466,25 +469,33 @@ function splitSegments(command) {
             continue;
         }
         if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
-            parts.push(buffer);
+            parts.push({ text: buffer, start: bufferStart });
             buffer = '';
             i += 1;
+            bufferStart = i + 1;
             continue;
         }
         if (char === ';' || char === '|' || char === '\n') {
-            parts.push(buffer);
+            parts.push({ text: buffer, start: bufferStart });
             buffer = '';
+            bufferStart = i + 1;
             continue;
         }
         if (char === '&' && command[i - 1] !== '>' && next !== '>') {
-            parts.push(buffer);
+            parts.push({ text: buffer, start: bufferStart });
             buffer = '';
+            bufferStart = i + 1;
             continue;
         }
         buffer += char;
     }
-    parts.push(buffer);
-    return parts.map((part) => part.trim()).filter(Boolean);
+    parts.push({ text: buffer, start: bufferStart });
+    return parts
+        .map((part) => ({
+        text: part.text.trim(),
+        start: part.start + (part.text.length - part.text.trimStart().length),
+    }))
+        .filter((part) => part.text !== '');
 }
 /**
  * One segment's words: quotes kept whole, grouping parentheses dropped, and a `(` written
@@ -506,6 +517,38 @@ function segmentWords(text) {
     }
     return cleaned;
 }
+/** {@link WORD} anchored at an offset, for walking a statement's raw words. */
+const WORD_AT = new RegExp(WORD.source, 'y');
+/**
+ * A statement's own leading `NAME=value` words, and where they end.
+ *
+ * The shell binds these to the command the statement runs, so they are the environment THAT
+ * program sees — which is why a caller writing a variable for a run has to write it here and not
+ * at the start of the whole command.
+ *
+ * @param text - One statement's text.
+ * @returns The assignments as written, and the offset in `text` just before the word that runs.
+ */
+function leadingAssignments(text) {
+    const words = [];
+    let at = 0;
+    for (let guard = 0; guard < MAX_WRAPPERS; guard++) {
+        while (at < text.length && /\s/.test(text[at] ?? ''))
+            at += 1;
+        // Grouping in front of the statement (`(npx …)`, `{ …`): not a word the shell assigns with.
+        if (text[at] === '(' || text[at] === '{') {
+            at += 1;
+            continue;
+        }
+        WORD_AT.lastIndex = at;
+        const match = WORD_AT.exec(text);
+        if (!match || !ENV_ASSIGNMENT.test(match[0]))
+            return { words, end: at };
+        words.push(match[0]);
+        at += match[0].length;
+    }
+    return { words, end: at };
+}
 /**
  * The segments of a command, each with its program and arguments — the answer every classifier
  * that reads a command as "this runs the suite" is asking for.
@@ -514,66 +557,92 @@ function segmentWords(text) {
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export function commandSegments(command) {
-    return segmentsOf(command, 0);
+    return locatedSegmentsOf(command, 0).flatMap((located) => located.segment === null ? [] : [located.segment]);
 }
 /**
- * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
- * under (`timeout 280 hurl --test …` → 280), or null when it carries none.
- *
- * This is the bound `man timeout` enforces by KILLING the command — so a run that used it did not
- * finish, whatever the pipeline's own exit status says. It is read here, from the same parse every
- * other command reader uses, rather than matched as text: `timeout` in an argument
- * (`grep -n 'timeout 280' notes.md`) bounds nothing, and `-k 5` is the grace before the kill, not
- * the bound ({@link WRAPPER_VALUE_FLAGS}).
+ * Every statement of a command, with its own assignments and where it sits — assignment-only
+ * statements included, because the variables those persist are exactly what a later statement of
+ * the same command reads.
  *
  * @param command - The shell command.
- * @returns The seconds the command allows itself, or null.
+ * @returns One entry per statement or pipeline stage, in order.
  */
-export function commandTimeoutSeconds(command) {
-    let bound = null;
-    for (const segment of segmentsOf(command, 0)) {
-        if (segment.timeoutSeconds === null)
-            continue;
-        bound = bound === null ? segment.timeoutSeconds : Math.max(bound, segment.timeoutSeconds);
-    }
-    return bound;
+export function locatedCommandSegments(command) {
+    return locatedSegmentsOf(command, 0);
 }
 /**
- * {@link commandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
- * {@link MAX_NESTING} allows.
+ * {@link locatedCommandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
+ * {@link MAX_NESTING} allows. A nested statement's offsets are cleared: they are positions in
+ * the nested string, not in the command this walk started from.
  *
  * @param command - The shell command.
  * @param depth - How many `sh -c` strings this command already sits inside.
- * @returns The segments.
+ * @returns The located statements.
  */
-function segmentsOf(command, depth) {
+function locatedSegmentsOf(command, depth) {
     if (typeof command !== 'string' || depth > MAX_NESTING)
         return [];
     const out = [];
-    for (const text of splitSegments(command)) {
-        const words = segmentWords(text);
-        if (words.length === 0)
-            continue;
+    for (const part of splitSegments(command)) {
+        const words = segmentWords(part.text);
         const start = commandStart(words);
+        const leading = leadingAssignments(part.text);
         if (start.nested !== null) {
-            out.push(...segmentsOf(start.nested, depth + 1));
+            for (const inner of locatedSegmentsOf(start.nested, depth + 1))
+                out.push({ ...inner, start: null, assignmentOffset: null });
             continue;
         }
         const word = words[start.at];
-        // Only wrappers and assignments: nothing this segment runs.
-        if (word === undefined)
+        if (word === undefined) {
+            // Only wrappers and assignments: nothing this statement runs, but the variables it sets
+            // persist in the shell the rest of the command runs in.
+            if (leading.words.length > 0)
+                out.push({
+                    segment: null,
+                    assignments: leading.words,
+                    start: part.start,
+                    assignmentOffset: part.start + leading.end,
+                });
             continue;
+        }
         const program = programName(word);
         const args = words.slice(start.at + 1);
         out.push({
-            program,
-            args,
-            text: [program, ...args].join(' '),
-            timeoutSeconds: start.timeoutSeconds,
+            segment: {
+                program,
+                args,
+                text: [program, ...args].join(' '),
+                timeoutSeconds: start.timeoutSeconds,
+            },
+            assignments: leading.words,
+            start: part.start,
+            assignmentOffset: part.start + leading.end,
         });
     }
     return out;
 }
+/**
+ * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
+ * under (`timeout 280 hurl --test …` → 280), or null when it carries none.
+ *
+ * This is the bound `man timeout` enforces by KILLING the command — so a run that used it did not
+ * finish, whatever the pipeline's own exit status says. It is read here, from the same parse every
+ * other command reader uses, rather than matched as text: `timeout` in an argument
+ * (`grep -n 'timeout 280' notes.md`) bounds nothing, and `-k 5` is the grace before the kill, not
+ * the bound ({@link WRAPPER_VALUE_FLAGS}).
+ *
+ * @param command - The shell command.
+ * @returns The seconds the command allows itself, or null.
+ */
+export function commandTimeoutSeconds(command) {
+    let bound = null;
+    for (const segment of commandSegments(command)) {
+        if (segment.timeoutSeconds === null)
+            continue;
+        bound = bound === null ? segment.timeoutSeconds : Math.max(bound, segment.timeoutSeconds);
+    }
+    return bound;
+}
 /**
  * Whether any segment of the command runs a program whose command-position text matches
  * `pattern` — the one question a runner-kind table asks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",