agentweaver 0.1.12 → 0.1.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seko99
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -85,6 +85,7 @@ User-invokable built-in commands currently map to these flow specs:
 - `run-go-linter-loop`
 - `auto-golang`
 - `auto-common`
+- `doctor`
 
 There are also built-in nested/helper flows that are loaded declaratively but are not direct top-level CLI commands, for example `review-project`.
 
@@ -215,6 +216,9 @@ agentweaver run-go-tests-loop DEMO-1234
 agentweaver run-go-linter-loop DEMO-1234
 agentweaver auto-golang DEMO-1234
 agentweaver auto-common DEMO-1234
+agentweaver doctor
+agentweaver doctor --json
+agentweaver doctor <category>|<check-id>
 ```
 
 From a source checkout:
@@ -237,6 +241,8 @@ agentweaver auto-common --help-phases
 agentweaver auto-golang --from <phase> DEMO-1234
 agentweaver auto-status DEMO-1234
 agentweaver auto-reset DEMO-1234
+agentweaver doctor
+agentweaver doctor --json
 ```
 
 Notes:

package/dist/doctor/checks/agentweaver-home.js

@@ -0,0 +1,57 @@
+import { accessSync, constants, existsSync } from "node:fs";
+import { DoctorStatus } from "../types.js";
+import { CATEGORY } from "./category.js";
+import { agentweaverHome } from "../../runtime/agentweaver-home.js";
+const PACKAGE_ROOT = process.cwd();
+export const agentweaverHomeCheck = {
+    id: "agentweaver-home-01",
+    category: CATEGORY.AGENTWEAVER_HOME,
+    title: "agentweaver-home",
+    dependencies: [],
+    execute: async () => {
+        const homePath = agentweaverHome(PACKAGE_ROOT);
+        if (!existsSync(homePath)) {
+            return {
+                id: "agentweaver-home-01",
+                status: DoctorStatus.Fail,
+                title: "agentweaver-home",
+                message: `Directory does not exist: ${homePath}`,
+                hint: "Create the ~/.agentweaver directory or set AGENTWEAVER_HOME environment variable",
+                details: `resolved path: ${homePath}`,
+            };
+        }
+        try {
+            accessSync(homePath, constants.R_OK | constants.W_OK);
+            return {
+                id: "agentweaver-home-01",
+                status: DoctorStatus.Ok,
+                title: "agentweaver-home",
+                message: `Directory accessible and writable: ${homePath}`,
+                details: `resolved path: ${homePath}`,
+            };
+        }
+        catch {
+            try {
+                accessSync(homePath, constants.R_OK);
+                return {
+                    id: "agentweaver-home-01",
+                    status: DoctorStatus.Warn,
+                    title: "agentweaver-home",
+                    message: `Directory exists but is not writable: ${homePath}`,
+                    hint: "Check directory permissions; AgentWeaver needs write access to this directory",
+                    details: `resolved path: ${homePath}`,
+                };
+            }
+            catch {
+                return {
+                    id: "agentweaver-home-01",
+                    status: DoctorStatus.Fail,
+                    title: "agentweaver-home",
+                    message: `Directory exists but is not readable: ${homePath}`,
+                    hint: "Check directory permissions",
+                    details: `resolved path: ${homePath}`,
+                };
+            }
+        }
+    },
+};

package/dist/doctor/checks/category.js

@@ -0,0 +1,9 @@
+export const CATEGORY = {
+    SYSTEM: "system",
+    NODE_VERSION: "node-version",
+    AGENTWEAVER_HOME: "agentweaver-home",
+    CWD_CONTEXT: "cwd-context",
+    EXECUTORS: "executors",
+    ENV_DIAGNOSTICS: "env-diagnostics",
+    FLOW_READINESS: "flow-readiness",
+};

package/dist/doctor/checks/cwd-context.js

@@ -0,0 +1,69 @@
+import { accessSync, constants, existsSync } from "node:fs";
+import { DoctorStatus } from "../types.js";
+import { CATEGORY } from "./category.js";
+const SOFT_CHECK_ID = "cwd-context-01";
+export const cwdContextCheck = {
+    id: "cwd-context-01",
+    category: CATEGORY.CWD_CONTEXT,
+    title: "cwd-context",
+    dependencies: [],
+    execute: async () => {
+        const cwd = process.cwd();
+        let permissionStatus;
+        let permissionMessage;
+        let permissionHint;
+        try {
+            accessSync(cwd, constants.R_OK | constants.W_OK);
+            permissionStatus = DoctorStatus.Ok;
+            permissionMessage = "Working directory is readable and writable";
+            permissionHint = undefined;
+        }
+        catch {
+            try {
+                accessSync(cwd, constants.R_OK);
+                permissionStatus = DoctorStatus.Warn;
+                permissionMessage = "Working directory is readable but not writable";
+                permissionHint = "Some operations may fail if write access is required";
+            }
+            catch {
+                permissionStatus = DoctorStatus.Fail;
+                permissionMessage = "Working directory is not readable";
+                permissionHint = "Check directory permissions";
+            }
+        }
+        const gitRepoExists = existsSync(".git");
+        const gitStatusMessage = gitRepoExists ? "git repository detected" : "not a git repository";
+        const gitStatus = gitRepoExists ? DoctorStatus.Ok : DoctorStatus.Warn;
+        if (permissionStatus === DoctorStatus.Ok && gitStatus === DoctorStatus.Ok) {
+            return {
+                id: "cwd-context-01",
+                status: DoctorStatus.Ok,
+                title: "cwd-context",
+                message: `${permissionMessage}; ${gitStatusMessage}`,
+                details: `cwd: ${cwd}, git: ${gitStatusMessage}`,
+            };
+        }
+        if (permissionStatus === DoctorStatus.Ok && gitStatus === DoctorStatus.Warn) {
+            return {
+                id: "cwd-context-01",
+                status: DoctorStatus.Warn,
+                title: "cwd-context",
+                message: `${permissionMessage}; ${gitStatusMessage} (soft warning)`,
+                hint: "Git repository is recommended but not required",
+                details: `cwd: ${cwd}, git: ${gitStatusMessage}`,
+            };
+        }
+        const result = {
+            id: "cwd-context-01",
+            status: permissionStatus,
+            title: "cwd-context",
+            message: permissionMessage,
+            details: `cwd: ${cwd}, git: ${gitStatusMessage}`,
+        };
+        if (permissionHint) {
+            result.hint = permissionHint;
+        }
+        return result;
+    },
+};
+export const SOFT_CHECK_IDS = [SOFT_CHECK_ID];

package/dist/doctor/checks/env-diagnostics.js

@@ -0,0 +1,171 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DoctorStatus } from "../types.js";
+import { CATEGORY } from "./category.js";
+const MONITORED_KEYS = [
+    "JIRA_API_KEY",
+    "JIRA_USERNAME",
+    "JIRA_AUTH_MODE",
+    "JIRA_BASE_URL",
+    "GITLAB_TOKEN",
+    "AGENTWEAVER_HOME",
+    "CODEX_BIN",
+    "CODEX_MODEL",
+    "OPENCODE_BIN",
+    "OPENCODE_MODEL",
+];
+const SECRET_KEYS = new Set(["JIRA_API_KEY", "GITLAB_TOKEN"]);
+const JIRA_AUTH_MODE_ALLOWED_VALUES = ["auto", "basic", "bearer"];
+function maskSecret(value) {
+    if (value.length <= 6) {
+        if (value.length <= 3) {
+            return "***";
+        }
+        const start = value.slice(0, Math.ceil(value.length / 2));
+        const end = value.slice(Math.ceil(value.length / 2));
+        return `${start}***${end}`;
+    }
+    const start = value.slice(0, 3);
+    const end = value.slice(-3);
+    return `${start}***${end}`;
+}
+function globalConfigDir() {
+    return path.join(os.homedir(), ".agentweaver");
+}
+function parseEnvFileRaw(envFilePath) {
+    const result = {};
+    if (!existsSync(envFilePath)) {
+        return result;
+    }
+    const lines = readFileSync(envFilePath, "utf8").split(/\r?\n/);
+    for (const rawLine of lines) {
+        let line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        if (line.startsWith("export ")) {
+            line = line.slice(7).trim();
+        }
+        const separatorIndex = line.indexOf("=");
+        if (separatorIndex < 0) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        if (!key) {
+            continue;
+        }
+        let value = line.slice(separatorIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function getProjectEnvPath() {
+    return path.join(process.cwd(), ".agentweaver", ".env");
+}
+function getGlobalEnvPath() {
+    return path.join(globalConfigDir(), ".env");
+}
+function determineSource(key, shellSnapshot, currentValue) {
+    if (currentValue === null) {
+        return "missing";
+    }
+    const isInShellSnapshot = shellSnapshot.hasOwnProperty(key);
+    if (isInShellSnapshot) {
+        return "shell";
+    }
+    const globalEnv = parseEnvFileRaw(getGlobalEnvPath());
+    if (globalEnv.hasOwnProperty(key)) {
+        return "global";
+    }
+    const projectEnv = parseEnvFileRaw(getProjectEnvPath());
+    if (projectEnv.hasOwnProperty(key)) {
+        return "project-local";
+    }
+    return "shell";
+}
+function getDefaultValue(key) {
+    switch (key) {
+        case "AGENTWEAVER_HOME":
+            return path.join(os.homedir(), ".agentweaver");
+        default:
+            return null;
+    }
+}
+function validateJiraAuthMode(value) {
+    if (value === null) {
+        return true;
+    }
+    return JIRA_AUTH_MODE_ALLOWED_VALUES.includes(value);
+}
+function checkEnvDiagnostics() {
+    const shellSnapshot = {};
+    for (const key of Object.keys(process.env)) {
+        shellSnapshot[key] = process.env[key];
+    }
+    const projectEnv = parseEnvFileRaw(getProjectEnvPath());
+    const globalEnv = parseEnvFileRaw(getGlobalEnvPath());
+    const keyInfos = [];
+    let hasWarnings = false;
+    for (const key of MONITORED_KEYS) {
+        const currentValue = process.env[key] ?? null;
+        const source = determineSource(key, shellSnapshot, currentValue);
+        const isSecret = SECRET_KEYS.has(key);
+        let maskedValue = null;
+        if (currentValue !== null && isSecret) {
+            maskedValue = maskSecret(currentValue);
+        }
+        else if (currentValue !== null) {
+            maskedValue = currentValue;
+        }
+        const keyInfo = {
+            key,
+            source,
+            value: currentValue,
+            maskedValue,
+            isSecret,
+        };
+        keyInfos.push(keyInfo);
+        if (source === "missing") {
+            hasWarnings = true;
+        }
+        if (key === "JIRA_AUTH_MODE" && currentValue !== null) {
+            if (!validateJiraAuthMode(currentValue)) {
+                hasWarnings = true;
+            }
+        }
+    }
+    const status = hasWarnings ? DoctorStatus.Warn : DoctorStatus.Ok;
+    const keyCount = keyInfos.length;
+    const missingCount = keyInfos.filter(k => k.source === "missing").length;
+    const secretCount = keyInfos.filter(k => k.isSecret).length;
+    const summaryParts = [];
+    summaryParts.push(`${keyCount} keys checked`);
+    if (missingCount > 0) {
+        summaryParts.push(`${missingCount} missing`);
+    }
+    if (secretCount > 0) {
+        summaryParts.push(`${secretCount} secrets`);
+    }
+    const result = {
+        id: "env-diagnostics-01",
+        status,
+        title: "env-config",
+        message: summaryParts.join(", "),
+        ...(missingCount > 0 ? { hint: `${missingCount} configuration keys are missing` } : {}),
+        details: JSON.stringify(keyInfos),
+    };
+    return result;
+}
+export const envDiagnosticsCheck = {
+    id: "env-diagnostics-01",
+    category: CATEGORY.ENV_DIAGNOSTICS,
+    title: "env-config",
+    dependencies: [],
+    execute: async () => {
+        return checkEnvDiagnostics();
+    },
+};

package/dist/doctor/checks/executors.js

@@ -0,0 +1,106 @@
+import { spawnSync } from "node:child_process";
+import { DoctorStatus } from "../types.js";
+import { CATEGORY } from "./category.js";
+import { ALLOWED_MODELS_BY_EXECUTOR } from "../../pipeline/launch-profile-config.js";
+import { findCmdPath, isExecutable } from "../../runtime/command-resolution.js";
+function getEnvVarName(executorId) {
+    return executorId === "codex" ? "CODEX_BIN" : "OPENCODE_BIN";
+}
+function getCommandName(executorId) {
+    return executorId === "codex" ? "codex" : "opencode";
+}
+function resolveBinaryPath(executorId) {
+    const envVarName = getEnvVarName(executorId);
+    const commandName = getCommandName(executorId);
+    const configuredPath = process.env[envVarName];
+    if (configuredPath) {
+        if (isExecutable(configuredPath)) {
+            return { path: configuredPath, source: "env-override" };
+        }
+        return { path: null, source: "not-found" };
+    }
+    const foundPath = findCmdPath(commandName, "");
+    if (foundPath) {
+        return { path: foundPath, source: "PATH" };
+    }
+    return { path: null, source: "not-found" };
+}
+function runSmokeCheck(executorPath) {
+    const result = spawnSync(executorPath, ["--version"], { encoding: "utf8", stdio: "pipe" });
+    if (result.status === 0 && result.stdout) {
+        return result.stdout.trim();
+    }
+    return null;
+}
+function buildDetailsObj(executorId, resolution, versionOutput) {
+    return {
+        path: resolution.path,
+        source: resolution.source,
+        executable: resolution.path !== null && isExecutable(resolution.path),
+        versionOutput,
+    };
+}
+function createResult(executorId, status, message, hint, details, resolution, versionOutput) {
+    const result = {
+        id: `${executorId}-executor-01`,
+        status,
+        title: executorId,
+        message,
+    };
+    if (hint) {
+        result.hint = hint;
+    }
+    if (details) {
+        result.details = details;
+    }
+    result.detailsObj = buildDetailsObj(executorId, resolution, versionOutput);
+    return result;
+}
+function checkExecutor(executorId) {
+    const resolution = resolveBinaryPath(executorId);
+    if (resolution.path === null) {
+        const hint = executorId === "codex"
+            ? "Set CODEX_BIN environment variable to point to the codex binary"
+            : "Set OPENCODE_BIN environment variable to point to the opencode binary";
+        return createResult(executorId, DoctorStatus.Fail, `${executorId} binary not found`, hint, `source: ${resolution.source}`, resolution, null);
+    }
+    if (!isExecutable(resolution.path)) {
+        const hint = `Binary at ${resolution.path} is not executable`;
+        return createResult(executorId, DoctorStatus.Fail, `${executorId} binary is not executable`, hint, `path: ${resolution.path}`, resolution, null);
+    }
+    const versionOutput = runSmokeCheck(resolution.path);
+    if (versionOutput === null) {
+        return createResult(executorId, DoctorStatus.Fail, `${executorId} --version check failed`, `${executorId} --version did not produce expected output`, `path: ${resolution.path}, source: ${resolution.source}`, resolution, null);
+    }
+    const allowedModels = ALLOWED_MODELS_BY_EXECUTOR[executorId];
+    const modelWarnings = [];
+    for (const model of allowedModels) {
+        const modelResult = spawnSync(resolution.path, ["--model", model, "--version"], { encoding: "utf8", stdio: "pipe" });
+        if (modelResult.status !== 0) {
+            modelWarnings.push(`Model '${model}' validation failed (exit code ${modelResult.status})`);
+        }
+    }
+    const message = versionOutput;
+    if (modelWarnings.length > 0) {
+        return createResult(executorId, DoctorStatus.Warn, message, `Some models failed validation: ${modelWarnings.join("; ")}`, `source: ${resolution.source}, models validated: ${allowedModels.join(", ")}`, resolution, versionOutput);
+    }
+    return createResult(executorId, DoctorStatus.Ok, message, undefined, `source: ${resolution.source}`, resolution, versionOutput);
+}
+export const codexExecutorCheck = {
+    id: "codex-executor-01",
+    category: CATEGORY.EXECUTORS,
+    title: "codex",
+    dependencies: [],
+    execute: async () => {
+        return checkExecutor("codex");
+    },
+};
+export const opencodeExecutorCheck = {
+    id: "opencode-executor-01",
+    category: CATEGORY.EXECUTORS,
+    title: "opencode",
+    dependencies: [],
+    execute: async () => {
+        return checkExecutor("opencode");
+    },
+};