@llm4ts/runner 0.3.0 → 0.4.0

package/dist/Doctor.d.ts

@@ -1,4 +1,26 @@
 import * as Effect from "effect/Effect";
 import type { ConnectorRegistryShape } from "@llm4ts/core/ConnectorRegistry";
+export interface PrerequisiteReport {
+    readonly satisfied: boolean;
+    readonly summary: string;
+    readonly hint?: string;
+}
+/**
+ * The Gemini CLI resolves credentials from the environment before it ever
+ * looks at a prompt, and a Workspace or enterprise account with no project
+ * configured fails during auth setup with "No project found" / "requires
+ * setting the GOOGLE_CLOUD_PROJECT … env var" — a message that names nothing
+ * about llm4ts and is easy to misread as a flow bug.
+ *
+ * The CLI accepts several routes; any one of them is enough:
+ *   - `GEMINI_API_KEY` (AI Studio key),
+ *   - Vertex AI (`GOOGLE_GENAI_USE_VERTEXAI` plus a project or `GOOGLE_API_KEY`),
+ *   - `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_PROJECT_ID` for Code Assist,
+ *   - or a personal OAuth login, which needs no environment at all.
+ *
+ * Personal OAuth cannot be observed from the environment, so an unconfigured
+ * environment is reported as a caveat rather than a failure.
+ */
+export declare const geminiPrerequisites: (environment: Readonly<Record<string, string | undefined>>) => PrerequisiteReport;
 export declare const makeDoctorProgram: (registry?: ConnectorRegistryShape, environment?: Readonly<Record<string, string | undefined>>) => Effect.Effect<string>;
 //# sourceMappingURL=Doctor.d.ts.map

package/dist/Doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Doctor.d.ts","sourceRoot":"","sources":["../src/Doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AAiB5E,eAAO,MAAM,iBAAiB,GAC5B,WAAU,sBAA8D,EACxE,cAAa,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,KACtE,MAAM,CAAC,MAAM,CAAC,MAAM,CAqBnB,CAAA"}
+{"version":3,"file":"Doctor.d.ts","sourceRoot":"","sources":["../src/Doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AAuB5E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,KACxD,kBA0BF,CAAA;AAwBD,eAAO,MAAM,iBAAiB,GAC5B,WAAU,sBAA8D,EACxE,cAAa,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,KACtE,MAAM,CAAC,MAAM,CAAC,MAAM,CAwCnB,CAAA"}

package/dist/Doctor.js

@@ -1,4 +1,5 @@
 import * as Effect from "effect/Effect";
+import { ConnectorIds } from "@llm4ts/core/Models";
 import { nodeFlowRunnerDependencies } from "./FlowRunner.js";
 const credentialKeys = [
     "OPENAI_API_KEY",
@@ -11,6 +12,70 @@ const statusLine = (id, status) => {
     const auth = status.authStatus === "Unknown" ? "" : `  auth: ${status.authStatus.toLowerCase()}`;
     return `  ${mark} ${id.padEnd(14)} ${status.availability.toLowerCase()}${auth}`;
 };
+const isSet = (value) => value !== undefined && value.trim().length > 0;
+const truthy = (value) => isSet(value) && ["1", "true", "yes"].includes(value.trim().toLowerCase());
+/**
+ * The Gemini CLI resolves credentials from the environment before it ever
+ * looks at a prompt, and a Workspace or enterprise account with no project
+ * configured fails during auth setup with "No project found" / "requires
+ * setting the GOOGLE_CLOUD_PROJECT … env var" — a message that names nothing
+ * about llm4ts and is easy to misread as a flow bug.
+ *
+ * The CLI accepts several routes; any one of them is enough:
+ *   - `GEMINI_API_KEY` (AI Studio key),
+ *   - Vertex AI (`GOOGLE_GENAI_USE_VERTEXAI` plus a project or `GOOGLE_API_KEY`),
+ *   - `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_PROJECT_ID` for Code Assist,
+ *   - or a personal OAuth login, which needs no environment at all.
+ *
+ * Personal OAuth cannot be observed from the environment, so an unconfigured
+ * environment is reported as a caveat rather than a failure.
+ */
+export const geminiPrerequisites = (environment) => {
+    const project = environment.GOOGLE_CLOUD_PROJECT ?? environment.GOOGLE_CLOUD_PROJECT_ID;
+    const vertex = truthy(environment.GOOGLE_GENAI_USE_VERTEXAI);
+    if (isSet(environment.GEMINI_API_KEY)) {
+        return { satisfied: true, summary: "GEMINI_API_KEY is set" };
+    }
+    if (vertex && (isSet(project) || isSet(environment.GOOGLE_API_KEY))) {
+        return {
+            satisfied: true,
+            summary: isSet(project)
+                ? `Vertex AI with GOOGLE_CLOUD_PROJECT=${project.trim()}`
+                : "Vertex AI with GOOGLE_API_KEY"
+        };
+    }
+    if (isSet(project)) {
+        return { satisfied: true, summary: `GOOGLE_CLOUD_PROJECT=${project.trim()}` };
+    }
+    return {
+        satisfied: false,
+        summary: "no project or API key in the environment",
+        hint: "a personal OAuth login still works; a Workspace or enterprise account fails at auth " +
+            'setup with "No project found". Export GOOGLE_CLOUD_PROJECT (or GEMINI_API_KEY) in a file ' +
+            "every shell reads — a login-only file such as ~/.bashrc is not read by non-interactive " +
+            "shells, other shells, or IDE terminals."
+    };
+};
+/** Wraps a hint to the terminal-friendly width the rest of the report uses. */
+const wrap = (text, width, indent) => {
+    const out = [];
+    let line = "";
+    for (const word of text.split(/\s+/).filter((part) => part.length > 0)) {
+        const candidate = line.length === 0 ? word : `${line} ${word}`;
+        if (candidate.length + indent.length > width && line.length > 0) {
+            out.push(`${indent}${line}`);
+            line = word;
+        }
+        else {
+            line = candidate;
+        }
+    }
+    if (line.length > 0) {
+        out.push(`${indent}${line}`);
+    }
+    return out;
+};
+const selectedCoder = (environment) => environment.LLM4TS_CODER ?? environment.LLM4ZIO_CODER ?? "claude (default)";
 export const makeDoctorProgram = (registry = nodeFlowRunnerDependencies().registry, environment = process.env) => Effect.map(registry.healthCheckAll, (statuses) => {
     const lines = [];
     lines.push("llm4ts doctor");
@@ -26,8 +91,23 @@ export const makeDoctorProgram = (registry = nodeFlowRunnerDependencies().regist
         const value = environment[key];
         lines.push(`  ${value === undefined || value.length === 0 ? "✖" : "✔"} ${key}`);
     }
+    // Connector prerequisites the environment must carry BEFORE a run: shown
+    // when the connector is selected or the machine has its CLI, because that
+    // is exactly when a missing one turns into a confusing mid-run failure.
+    const coder = selectedCoder(environment);
+    const geminiRelevant = coder.startsWith("gemini") ||
+        Array.from(statuses.keys()).some((id) => id.value === ConnectorIds.GeminiCli.value || id.value === ConnectorIds.GeminiApi.value);
+    if (geminiRelevant) {
+        const gemini = geminiPrerequisites(environment);
+        lines.push("");
+        lines.push("prerequisites:");
+        lines.push(`  ${gemini.satisfied ? "✔" : "?"} gemini: ${gemini.summary}`);
+        if (gemini.hint !== undefined) {
+            lines.push(...wrap(gemini.hint, 78, "      "));
+        }
+    }
     lines.push("");
-    lines.push(`coder: ${environment.LLM4TS_CODER ?? environment.LLM4ZIO_CODER ?? "claude (default)"}`);
+    lines.push(`coder: ${coder}`);
     return `${lines.join("\n")}\n`;
 });
 //# sourceMappingURL=Doctor.js.map

package/dist/Doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"Doctor.js","sourceRoot":"","sources":["../src/Doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AAE5D,MAAM,cAAc,GAAG;IACrB,gBAAgB;IAChB,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;CACR,CAAA;AAEV,MAAM,UAAU,GAAG,CAAC,EAAU,EAAE,MAAoB,EAAU,EAAE;IAC9D,MAAM,IAAI,GACR,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;IACzF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,CAAA;IAChG,OAAO,KAAK,IAAI,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,GAAG,IAAI,EAAE,CAAA;AACjF,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,WAAmC,0BAA0B,EAAE,CAAC,QAAQ,EACxE,cAA4D,OAAO,CAAC,GAAG,EAChD,EAAE,CACzB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,EAAE;IAC/C,MAAM,KAAK,GAAkB,EAAE,CAAA;IAC/B,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IACzB,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;IAChG,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IAC1B,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;QAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC,CAAA;IACjF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,IAAI,CACR,UAAU,WAAW,CAAC,YAAY,IAAI,WAAW,CAAC,aAAa,IAAI,kBAAkB,EAAE,CACxF,CAAA;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AAChC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"Doctor.js","sourceRoot":"","sources":["../src/Doctor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/runner",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Node runner, CLI, terminal, and MCP composition for llm4ts",
   "license": "MIT",
   "type": "module",
@@ -55,8 +55,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/flow": "0.3.0",
-    "@llm4ts/core": "0.3.0"
+    "@llm4ts/core": "0.4.0",
+    "@llm4ts/flow": "0.4.0"
   },
   "peerDependencies": {
     "effect": "^4.0.0-beta.102"

package/src/Doctor.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect"
 import type { HealthStatus } from "@llm4ts/core/Models"
+import { ConnectorIds } from "@llm4ts/core/Models"
 import type { ConnectorRegistryShape } from "@llm4ts/core/ConnectorRegistry"
 import { nodeFlowRunnerDependencies } from "./FlowRunner.ts"
 
@@ -17,6 +18,86 @@ const statusLine = (id: string, status: HealthStatus): string => {
   return `  ${mark} ${id.padEnd(14)} ${status.availability.toLowerCase()}${auth}`
 }
 
+const isSet = (value: string | undefined): value is string =>
+  value !== undefined && value.trim().length > 0
+
+const truthy = (value: string | undefined): boolean =>
+  isSet(value) && ["1", "true", "yes"].includes(value.trim().toLowerCase())
+
+export interface PrerequisiteReport {
+  readonly satisfied: boolean
+  readonly summary: string
+  readonly hint?: string
+}
+
+/**
+ * The Gemini CLI resolves credentials from the environment before it ever
+ * looks at a prompt, and a Workspace or enterprise account with no project
+ * configured fails during auth setup with "No project found" / "requires
+ * setting the GOOGLE_CLOUD_PROJECT … env var" — a message that names nothing
+ * about llm4ts and is easy to misread as a flow bug.
+ *
+ * The CLI accepts several routes; any one of them is enough:
+ *   - `GEMINI_API_KEY` (AI Studio key),
+ *   - Vertex AI (`GOOGLE_GENAI_USE_VERTEXAI` plus a project or `GOOGLE_API_KEY`),
+ *   - `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_PROJECT_ID` for Code Assist,
+ *   - or a personal OAuth login, which needs no environment at all.
+ *
+ * Personal OAuth cannot be observed from the environment, so an unconfigured
+ * environment is reported as a caveat rather than a failure.
+ */
+export const geminiPrerequisites = (
+  environment: Readonly<Record<string, string | undefined>>
+): PrerequisiteReport => {
+  const project = environment.GOOGLE_CLOUD_PROJECT ?? environment.GOOGLE_CLOUD_PROJECT_ID
+  const vertex = truthy(environment.GOOGLE_GENAI_USE_VERTEXAI)
+  if (isSet(environment.GEMINI_API_KEY)) {
+    return { satisfied: true, summary: "GEMINI_API_KEY is set" }
+  }
+  if (vertex && (isSet(project) || isSet(environment.GOOGLE_API_KEY))) {
+    return {
+      satisfied: true,
+      summary: isSet(project)
+        ? `Vertex AI with GOOGLE_CLOUD_PROJECT=${project.trim()}`
+        : "Vertex AI with GOOGLE_API_KEY"
+    }
+  }
+  if (isSet(project)) {
+    return { satisfied: true, summary: `GOOGLE_CLOUD_PROJECT=${project.trim()}` }
+  }
+  return {
+    satisfied: false,
+    summary: "no project or API key in the environment",
+    hint:
+      "a personal OAuth login still works; a Workspace or enterprise account fails at auth " +
+      'setup with "No project found". Export GOOGLE_CLOUD_PROJECT (or GEMINI_API_KEY) in a file ' +
+      "every shell reads — a login-only file such as ~/.bashrc is not read by non-interactive " +
+      "shells, other shells, or IDE terminals."
+  }
+}
+
+/** Wraps a hint to the terminal-friendly width the rest of the report uses. */
+const wrap = (text: string, width: number, indent: string): ReadonlyArray<string> => {
+  const out: Array<string> = []
+  let line = ""
+  for (const word of text.split(/\s+/).filter((part) => part.length > 0)) {
+    const candidate = line.length === 0 ? word : `${line} ${word}`
+    if (candidate.length + indent.length > width && line.length > 0) {
+      out.push(`${indent}${line}`)
+      line = word
+    } else {
+      line = candidate
+    }
+  }
+  if (line.length > 0) {
+    out.push(`${indent}${line}`)
+  }
+  return out
+}
+
+const selectedCoder = (environment: Readonly<Record<string, string | undefined>>): string =>
+  environment.LLM4TS_CODER ?? environment.LLM4ZIO_CODER ?? "claude (default)"
+
 export const makeDoctorProgram = (
   registry: ConnectorRegistryShape = nodeFlowRunnerDependencies().registry,
   environment: Readonly<Record<string, string | undefined>> = process.env
@@ -36,9 +117,28 @@ export const makeDoctorProgram = (
       const value = environment[key]
       lines.push(`  ${value === undefined || value.length === 0 ? "✖" : "✔"} ${key}`)
     }
+
+    // Connector prerequisites the environment must carry BEFORE a run: shown
+    // when the connector is selected or the machine has its CLI, because that
+    // is exactly when a missing one turns into a confusing mid-run failure.
+    const coder = selectedCoder(environment)
+    const geminiRelevant =
+      coder.startsWith("gemini") ||
+      Array.from(statuses.keys()).some(
+        (id) =>
+          id.value === ConnectorIds.GeminiCli.value || id.value === ConnectorIds.GeminiApi.value
+      )
+    if (geminiRelevant) {
+      const gemini = geminiPrerequisites(environment)
+      lines.push("")
+      lines.push("prerequisites:")
+      lines.push(`  ${gemini.satisfied ? "✔" : "?"} gemini: ${gemini.summary}`)
+      if (gemini.hint !== undefined) {
+        lines.push(...wrap(gemini.hint, 78, "      "))
+      }
+    }
+
     lines.push("")
-    lines.push(
-      `coder: ${environment.LLM4TS_CODER ?? environment.LLM4ZIO_CODER ?? "claude (default)"}`
-    )
+    lines.push(`coder: ${coder}`)
     return `${lines.join("\n")}\n`
   })