@sireai/optimus 0.1.1 → 0.1.3

package/dist/cli/optimus.js

@@ -28,11 +28,13 @@ import { TaskDeliveryService } from "../task-environment/delivery/task-delivery-
 import { FeishuAnalysisDocService } from "../task-environment/delivery/feishu-analysis-doc-service.js";
 import { TaskPublicationService } from "../task-environment/delivery/task-publication-service.js";
 import { resolveDefaultConfigPath, resolveDefaultEnvPath, resolveOptimusHomeDir } from "../config/optimus-paths.js";
-import { checkForSelfUpdate, installSelfUpdate, readSelfUpdateState } from "./self-update.js";
+import { checkForSelfUpdate, installSelfUpdate, recordSkippedSelfUpdate, readSelfUpdateState } from "./self-update.js";
 const CLI_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const PACKAGE_JSON_PATH = join(CLI_ROOT_DIR, "package.json");
 const execFileAsync = promisify(execFile);
 const PACKAGE_NAME = "@sireai/optimus";
+const JIRA_CLI_ENTRY = join(CLI_ROOT_DIR, "dist", "integrations", "jira", "jira-cli.js");
+const RELEASE_NOTES_URL = "https://github.com/SireAI/optimus/releases/latest";
 function renderSetupResult(result) {
     const lines = [];
     lines.push("Setup Complete");
@@ -130,39 +132,41 @@ function renderCliHelp() {
         "Usage:",
         "  optimus <command> [options]",
         "",
-        "First-time setup:",
+        "Get started:",
         "  optimus setup",
-        "  optimus doctor --quick",
+        "  optimus start",
         "  optimus submit --title \"Login crash\" --description \"Crash on startup\"",
         "",
-        "Core commands:",
-        "  start                 Start the resident runtime",
-        "  submit                Submit a manual task",
-        "  upgrade               Check for or install the latest Optimus version",
-        "  retry-task            Requeue an existing task",
-        "  cancel-task           Cancel a queued or running task",
-        "  triage-only           Run resident triage without enqueuing a task",
-        "",
-        "Repository commands:",
+        "User commands:",
+        "  help [command]       Show CLI help or command help",
+        "  setup                Configure Optimus for first use or update config",
+        "  start                Start the resident runtime",
+        "  submit               Submit a manual task",
+        "  retry-task           Requeue an existing task",
+        "  cancel-task          Cancel a queued or running task",
+        "  task-status          Show task execution status",
+        "  task-result          Show persisted result, delivery, and publication data",
+        "  task-events          Show task timeline",
         "  repo add|remove|update|list|doctor",
+        "  doctor               Show runtime, skills, and environment diagnostics",
+        "  health-check         Validate Codex/provider readiness",
+        "  upgrade              Check for or install the latest Optimus version",
+        "  version              Show the installed package version",
         "",
-        "Inspection commands:",
-        "  health-check          Validate Codex/provider readiness",
-        "  doctor                Show runtime, skills, and environment diagnostics",
-        "  task-status           Show task execution status",
-        "  task-result           Show persisted result, delivery, and publication data",
+        "Advanced commands:",
         "  delivery-status       Show focused delivery/publication state",
-        "  task-events           Show task timeline",
-        "  db-inspect            Show raw persisted task data",
-        "",
-        "Delivery commands:",
         "  notify-test           Send or preview a Feishu test notification",
         "  delivery-retry        Replay notification delivery from persisted bundle data",
         "  postrun-retry         Rebuild postrun artifacts and optionally replay publication",
         "",
         "Integration commands:",
+        "  jira-search|jira-get-issue|jira-search-assigned-open|jira-submit-issue|jira-submit-assigned-open|jira-add-comment|jira-poll-once|jira-poll-daemon",
+        "  Example: optimus help jira-submit-issue",
+        "",
+        "Developer commands:",
+        "  triage-only           Run resident triage without enqueuing a task",
         "  intake-status|intake-run|intake-disable|intake-enable|intake-reset-checkpoint",
-        "  jira-search|jira-get-issue|jira-search-assigned-open|jira-submit-issue|jira-submit-assigned-open|jira-poll-once|jira-poll-daemon",
+        "  db-inspect            Show raw persisted task data",
         "",
         "Global options:",
         "  -h, --help            Show this help",
@@ -173,24 +177,370 @@ function renderCliHelp() {
         `  - Run \`optimus setup\` once; Optimus stores config and runtime data under ${resolveOptimusHomeDir()}.`
     ].join("\n");
 }
+function renderCommandHelp(command) {
+    const normalized = command.trim();
+    const helpByCommand = {
+        submit: [
+            "optimus submit",
+            "",
+            "Usage:",
+            "  optimus submit --title <title> --description <text> [options]",
+            "",
+            "Required:",
+            "  --title <title>              Task title",
+            "  --description <text>         Task description",
+            "",
+            "Common options:",
+            "  --repo <alias>               Target registered repository alias",
+            "  --task-type <type>           Task type, default bugfix",
+            "  --source-ref <id>            External issue key or source reference",
+            "  --allow-duplicate            Allow duplicate submission",
+            "",
+            "Example:",
+            "  optimus submit --title \"Login crash\" --description \"Crash on startup\" --repo ohos-pre"
+        ].join("\n"),
+        "retry-task": [
+            "optimus retry-task",
+            "",
+            "Usage:",
+            "  optimus retry-task --task-id <task-id> [options]",
+            "",
+            "Required:",
+            "  --task-id <task-id>          Existing task id",
+            "",
+            "Optional:",
+            "  --reason <text>              Retry reason"
+        ].join("\n"),
+        "cancel-task": [
+            "optimus cancel-task",
+            "",
+            "Usage:",
+            "  optimus cancel-task --task-id <task-id> [options]",
+            "",
+            "Required:",
+            "  --task-id <task-id>          Existing task id",
+            "",
+            "Optional:",
+            "  --reason <text>              Cancel reason",
+            "  --keep-artifacts             Keep task artifacts after cancel",
+            "  --force                      Force cancel metadata flag"
+        ].join("\n"),
+        "task-status": [
+            "optimus task-status",
+            "",
+            "Usage:",
+            "  optimus task-status [options]",
+            "",
+            "Optional:",
+            "  --task-id <task-id>          Filter by task id",
+            "  --status <status>            Filter by task status",
+            "  --active-only                Show active tasks only",
+            "  --limit <n>                  Max tasks to show, default 20"
+        ].join("\n"),
+        "task-result": [
+            "optimus task-result",
+            "",
+            "Usage:",
+            "  optimus task-result --task-id <task-id> [options]",
+            "",
+            "Required:",
+            "  --task-id <task-id>          Existing task id",
+            "",
+            "Optional:",
+            "  --format text                Print compact text report",
+            "  --print                      Alias for text output"
+        ].join("\n"),
+        "delivery-status": [
+            "optimus delivery-status",
+            "",
+            "Usage:",
+            "  optimus delivery-status --task-id <task-id> [options]",
+            "",
+            "Required:",
+            "  --task-id <task-id>          Existing task id",
+            "",
+            "Optional:",
+            "  --format text                Print compact text report",
+            "  --print                      Alias for text output"
+        ].join("\n"),
+        repo: [
+            "optimus repo",
+            "",
+            "Usage:",
+            "  optimus repo add <path> [options]",
+            "  optimus repo remove <path|alias>",
+            "  optimus repo update <path|alias> [options]",
+            "  optimus repo list",
+            "  optimus repo doctor",
+            "",
+            "Common options:",
+            "  --alias <name>               Repository alias",
+            "  --mode <copy|inplace>        Execution mode",
+            "",
+            "Examples:",
+            "  optimus repo add /path/to/repo --alias ohos-pre",
+            "  optimus repo update ohos-pre --mode inplace",
+            "  optimus repo remove ohos-pre"
+        ].join("\n"),
+        doctor: [
+            "optimus doctor",
+            "",
+            "Usage:",
+            "  optimus doctor [options]",
+            "",
+            "Optional:",
+            "  --quick                      Run compact readiness check",
+            "  --json                       Print JSON when used with --quick",
+            "  --format text                Print text report"
+        ].join("\n"),
+        "jira-submit-issue": [
+            "optimus jira-submit-issue",
+            "",
+            "Usage:",
+            "  optimus jira-submit-issue --issue-key <key> [options]",
+            "",
+            "Required:",
+            "  --issue-key <key>            Jira issue key, for example MICARAPPI-13178",
+            "",
+            "Common options:",
+            "  --repo <alias>               Target registered repository alias",
+            "  --branch <name>              Override target branch",
+            "  --task-type <type>           Task type, default bugfix",
+            "  --allow-duplicate            Allow duplicate submission",
+            "  --comment-limit <n>          Comment lines fetched from Jira, default 3",
+            "  --dry-run                    Preview without creating a task",
+            "",
+            "Example:",
+            "  optimus jira-submit-issue --issue-key MICARAPPI-13178 --repo ohos-pre --allow-duplicate"
+        ].join("\n"),
+        "jira-submit-assigned-open": [
+            "optimus jira-submit-assigned-open",
+            "",
+            "Usage:",
+            "  optimus jira-submit-assigned-open [options]",
+            "",
+            "Common options:",
+            "  --assignee <jira-user>       Jira assignee, default current user",
+            "  --repo <alias>               Target registered repository alias",
+            "  --projects-filter <csv>      Restrict Jira projects",
+            "  --limit <n>                  Max issues to submit, default 50",
+            "  --allow-duplicate            Allow duplicate submission",
+            "  --dry-run                    Preview without creating tasks"
+        ].join("\n"),
+        "jira-get-issue": [
+            "optimus jira-get-issue",
+            "",
+            "Usage:",
+            "  optimus jira-get-issue --issue-key <key> [options]",
+            "",
+            "Required:",
+            "  --issue-key <key>            Jira issue key",
+            "",
+            "Optional:",
+            "  --fields <csv>               Requested Jira fields",
+            "  --expand <csv>               Jira expand parameters",
+            "  --properties <csv>           Jira properties",
+            "  --comment-limit <n>          Comment limit, default 3",
+            "  --update-history true|false  Include update history"
+        ].join("\n"),
+        "jira-search": [
+            "optimus jira-search",
+            "",
+            "Usage:",
+            "  optimus jira-search --jql <jql> [options]",
+            "",
+            "Required:",
+            "  --jql <jql>                  Jira search JQL",
+            "",
+            "Optional:",
+            "  --limit <n>                  Max issues, default 50",
+            "  --start-at <n>               Start offset, default 0",
+            "  --fields <csv>               Requested Jira fields",
+            "  --expand <csv>               Jira expand parameters",
+            "  --projects-filter <csv>      Restrict Jira projects"
+        ].join("\n"),
+        "jira-search-assigned-open": [
+            "optimus jira-search-assigned-open",
+            "",
+            "Usage:",
+            "  optimus jira-search-assigned-open [options]",
+            "",
+            "Optional:",
+            "  --assignee <jira-user>       Jira assignee, default current user",
+            "  --limit <n>                  Max issues, default 50",
+            "  --start-at <n>               Start offset, default 0",
+            "  --fields <csv>               Requested Jira fields"
+        ].join("\n"),
+        "jira-add-comment": [
+            "optimus jira-add-comment",
+            "",
+            "Usage:",
+            "  optimus jira-add-comment --issue-key <key> --body <text>",
+            "",
+            "Required:",
+            "  --issue-key <key>            Jira issue key",
+            "  --body <text>                Comment body"
+        ].join("\n"),
+        "jira-poll-once": [
+            "optimus jira-poll-once",
+            "",
+            "Usage:",
+            "  optimus jira-poll-once [options]",
+            "",
+            "Common options:",
+            "  --assignee <jira-user>       Jira assignee, default current user",
+            "  --repo <alias>               Target registered repository alias",
+            "  --projects-filter <csv>      Restrict Jira projects",
+            "  --limit <n>                  Max issues, default 50",
+            "  --allow-duplicate            Allow duplicate submission",
+            "  --dry-run                    Preview without creating tasks"
+        ].join("\n"),
+        "jira-poll-daemon": [
+            "optimus jira-poll-daemon",
+            "",
+            "Usage:",
+            "  optimus jira-poll-daemon [options]",
+            "",
+            "Common options:",
+            "  --interval-ms <ms>           Poll interval, default 300000",
+            "  --assignee <jira-user>       Jira assignee, default current user",
+            "  --repo <alias>               Target registered repository alias",
+            "  --projects-filter <csv>      Restrict Jira projects",
+            "  --limit <n>                  Max issues per poll, default 50",
+            "  --allow-duplicate            Allow duplicate submission",
+            "  --dry-run                    Preview without creating tasks"
+        ].join("\n")
+    };
+    return helpByCommand[normalized];
+}
+function mapJiraCommand(command) {
+    switch (command) {
+        case "jira-search":
+            return "search";
+        case "jira-get-issue":
+            return "get-issue";
+        case "jira-search-assigned-open":
+            return "search-assigned-open";
+        case "jira-submit-issue":
+            return "submit-issue";
+        case "jira-submit-assigned-open":
+            return "submit-assigned-open";
+        case "jira-add-comment":
+            return "add-comment";
+        case "jira-poll-once":
+            return "poll-once";
+        case "jira-poll-daemon":
+            return "poll-daemon";
+        default:
+            return undefined;
+    }
+}
+function resolveJiraQuickDoctorIssues(config) {
+    const issues = [];
+    if (!config.baseUrl?.trim() || /jira\.example\.com/i.test(config.baseUrl)) {
+        issues.push({
+            code: "jira_base_url_missing",
+            message: "Jira integration is enabled, but Jira base URL is missing or still using the placeholder value.",
+            fix: "Rerun `optimus setup` and provide a real Jira base URL."
+        });
+    }
+    if (config.authType === "bearer") {
+        if (!config.bearerToken?.trim()) {
+            issues.push({
+                code: "jira_token_missing",
+                message: "Jira integration is enabled, but Jira bearer token is missing.",
+                fix: "Rerun `optimus setup` and provide a Jira token."
+            });
+        }
+        return issues;
+    }
+    if (config.authType === "basic") {
+        if (!config.username?.trim() || !(config.apiToken?.trim() || config.password?.trim())) {
+            issues.push({
+                code: "jira_basic_auth_missing",
+                message: "Jira integration is enabled, but Jira basic auth credentials are incomplete.",
+                fix: "Provide Jira username plus api token or password, then rerun `optimus doctor --quick`."
+            });
+        }
+        return issues;
+    }
+    if (!config.mcpUrl?.trim() || /jira-mcp\.example\.com/i.test(config.mcpUrl)) {
+        issues.push({
+            code: "jira_mcp_url_missing",
+            message: "Jira integration is enabled, but Jira MCP URL is missing or still using the placeholder value.",
+            fix: "Provide a real Jira MCP URL, then rerun `optimus doctor --quick`."
+        });
+    }
+    const requiredHeaders = [
+        "X-Atlassian-Jira-Url",
+        "X-Atlassian-Username",
+        "X-Atlassian-Jira-Personal-Token"
+    ];
+    const missingHeaders = requiredHeaders.filter((name) => !config.httpHeaders[name]?.trim());
+    if (missingHeaders.length > 0) {
+        issues.push({
+            code: "jira_mcp_headers_missing",
+            message: `Jira integration is enabled, but Jira MCP headers are incomplete: ${missingHeaders.join(", ")}.`,
+            fix: "Provide the required Jira MCP headers, then rerun `optimus doctor --quick`."
+        });
+    }
+    return issues;
+}
+async function forwardJiraCliCommand(command, commandArgs) {
+    const mappedCommand = mapJiraCommand(command);
+    if (!mappedCommand) {
+        throw new Error(`Unsupported Jira command forwarding target: ${command}`);
+    }
+    const jiraCliEntry = process.env.OPTIMUS_JIRA_CLI_ENTRY?.trim() || JIRA_CLI_ENTRY;
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [jiraCliEntry, mappedCommand, ...commandArgs], {
+            cwd: process.cwd(),
+            env: process.env,
+            stdio: "inherit"
+        });
+        child.on("error", rejectPromise);
+        child.on("close", (code) => {
+            resolvePromise(code ?? 1);
+        });
+    });
+}
 async function readPackageVersion() {
     const raw = await readFile(PACKAGE_JSON_PATH, "utf8");
     const parsed = JSON.parse(raw);
     return parsed.version?.trim() || "0.0.0";
 }
-async function rerunCurrentCommand() {
-    const scriptPath = process.argv[1];
-    if (!scriptPath) {
-        throw new Error("Unable to resolve current Optimus entry script.");
-    }
-    return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, [scriptPath, ...process.argv.slice(2)], {
-            stdio: "inherit",
-            env: process.env
-        });
-        child.on("error", reject);
-        child.on("close", (code) => resolve(code ?? 1));
-    });
+function isInteractiveSelfUpdatePromptAllowed() {
+    return Boolean(input.isTTY && output.isTTY);
+}
+async function promptForStartupSelfUpdate(currentVersion, latestVersion) {
+    const rl = createInterface({ input, output });
+    try {
+        console.log("");
+        console.log(`Update available! ${currentVersion} -> ${latestVersion}`);
+        console.log("");
+        console.log(`Release notes: ${RELEASE_NOTES_URL}`);
+        console.log("");
+        console.log(`1. Update now (runs \`npm install -g ${PACKAGE_NAME}\`)`);
+        console.log("2. Skip");
+        console.log("3. Skip until next version");
+        console.log("");
+        while (true) {
+            const answer = (await rl.question("Press Enter to continue, or select [1/2/3] (default 2): ")).trim().toLowerCase();
+            if (!answer || answer === "2" || answer === "s" || answer === "skip") {
+                return "skip";
+            }
+            if (answer === "3" || answer === "n" || answer === "next") {
+                return "skip_until_next_version";
+            }
+            if (answer === "1" || answer === "u" || answer === "upgrade") {
+                return "upgrade";
+            }
+            console.log("Invalid selection. Enter 1, 2, or 3.");
+        }
+    }
+    finally {
+        rl.close();
+    }
 }
 async function maybeHandleStartupSelfUpdate(input) {
     const check = await checkForSelfUpdate({
@@ -222,7 +572,49 @@ async function maybeHandleStartupSelfUpdate(input) {
     if (!check.updateAvailable || !check.latestVersion) {
         return { handled: false };
     }
-    if ((input.config.selfUpdate ?? buildDefaultConfig().selfUpdate).mode !== "auto" || input.command !== "start") {
+    if (check.reason === "skipped_version") {
+        await input.logger.info("self_update.skipped_version", {
+            command: input.command,
+            currentVersion: check.currentVersion,
+            latestVersion: check.latestVersion
+        });
+        return { handled: false };
+    }
+    const selfUpdateConfig = input.config.selfUpdate ?? buildDefaultConfig().selfUpdate;
+    if (input.command !== "start") {
+        console.log(`[optimus] update available ${check.currentVersion} -> ${check.latestVersion}. Run \`optimus upgrade\`.`);
+        return { handled: false };
+    }
+    if (selfUpdateConfig.mode === "prompt") {
+        if (!isInteractiveSelfUpdatePromptAllowed()) {
+            console.log(`[optimus] update available ${check.currentVersion} -> ${check.latestVersion}. Run \`optimus upgrade\`.`);
+            return { handled: false };
+        }
+        const choice = await promptForStartupSelfUpdate(check.currentVersion, check.latestVersion);
+        await input.logger.info("self_update.prompt_resolved", {
+            command: input.command,
+            currentVersion: check.currentVersion,
+            latestVersion: check.latestVersion,
+            choice
+        });
+        if (choice === "skip") {
+            return { handled: false };
+        }
+        if (choice === "skip_until_next_version") {
+            await recordSkippedSelfUpdate({
+                currentVersion: check.currentVersion,
+                latestVersion: check.latestVersion,
+                packageRoot: CLI_ROOT_DIR
+            });
+            await input.logger.info("self_update.skip_until_next_version", {
+                command: input.command,
+                currentVersion: check.currentVersion,
+                latestVersion: check.latestVersion
+            });
+            return { handled: false };
+        }
+    }
+    else if (selfUpdateConfig.mode !== "auto") {
         console.log(`[optimus] update available ${check.currentVersion} -> ${check.latestVersion}. Run \`optimus upgrade\`.`);
         return { handled: false };
     }
@@ -245,7 +637,10 @@ async function maybeHandleStartupSelfUpdate(input) {
             latestVersion: check.latestVersion,
             reason: install.state.lastError ?? install.reason ?? "unknown"
         });
-        console.log(`[optimus] upgrade failed, continuing with ${check.currentVersion}.`);
+        console.log(`[optimus] upgrade failed. Continue with ${check.currentVersion}, or run \`optimus upgrade\` after fixing npm access.`);
+        if (selfUpdateConfig.mode === "auto") {
+            return { handled: true, exitCode: 1 };
+        }
         return { handled: false };
     }
     await input.logger.info("self_update.install_succeeded", {
@@ -253,10 +648,10 @@ async function maybeHandleStartupSelfUpdate(input) {
         currentVersion: check.currentVersion,
         latestVersion: check.latestVersion
     });
-    console.log(`[optimus] upgrade succeeded, restarting ${input.command}...`);
+    console.log(`[optimus] upgrade succeeded. Restart with \`optimus ${input.command}\`.`);
     return {
         handled: true,
-        exitCode: await rerunCurrentCommand()
+        exitCode: 0
     };
 }
 async function pathExists(path) {
@@ -430,8 +825,14 @@ async function promptSetupAnswers(defaults) {
         const jiraBaseUrl = enableJira
             ? (await ask(`Jira base URL [${defaults.jiraBaseUrl ?? ""}]: `)).trim() || defaults.jiraBaseUrl
             : undefined;
-        const jiraToken = enableJira
-            ? (await ask(`Jira token [${defaults.jiraToken ? "configured" : ""}]: `)).trim() || defaults.jiraToken
+        const jiraMcpUrl = enableJira
+            ? (await ask(`Jira MCP URL [${defaults.jiraMcpUrl ?? ""}]: `)).trim() || defaults.jiraMcpUrl
+            : undefined;
+        const jiraUsername = enableJira
+            ? (await ask(`Jira username [${defaults.jiraUsername ?? ""}]: `)).trim() || defaults.jiraUsername
+            : undefined;
+        const jiraPersonalToken = enableJira
+            ? (await ask(`Jira personal token [${defaults.jiraPersonalToken ? "configured" : ""}]: `)).trim() || defaults.jiraPersonalToken
             : undefined;
         return {
             repoPath,
@@ -447,7 +848,9 @@ async function promptSetupAnswers(defaults) {
             ...(feishuSecret ? { feishuSecret } : {}),
             enableJira,
             ...(jiraBaseUrl ? { jiraBaseUrl } : {}),
-            ...(jiraToken ? { jiraToken } : {})
+            ...(jiraMcpUrl ? { jiraMcpUrl } : {}),
+            ...(jiraUsername ? { jiraUsername } : {}),
+            ...(jiraPersonalToken ? { jiraPersonalToken } : {})
         };
     }
     finally {
@@ -492,7 +895,9 @@ async function resolveDefaultSetupAnswers() {
         ...(config.delivery.feishu.secret ? { feishuSecret: config.delivery.feishu.secret } : {}),
         enableJira: config.jira.enabled,
         ...(config.jira.baseUrl ? { jiraBaseUrl: config.jira.baseUrl } : {}),
-        ...(config.jira.bearerToken ? { jiraToken: config.jira.bearerToken } : {})
+        ...(config.jira.mcpUrl ? { jiraMcpUrl: config.jira.mcpUrl } : {}),
+        ...(config.jira.httpHeaders["X-Atlassian-Username"] ? { jiraUsername: config.jira.httpHeaders["X-Atlassian-Username"] } : {}),
+        ...(config.jira.httpHeaders["X-Atlassian-Jira-Personal-Token"] ? { jiraPersonalToken: config.jira.httpHeaders["X-Atlassian-Jira-Personal-Token"] } : {})
     };
 }
 function normalizeSetupCodexAuthMode(value) {
@@ -559,8 +964,14 @@ function validateSetupAnswers(answers) {
     if (answers.enableJira && !answers.jiraBaseUrl?.trim()) {
         return "setup requires a Jira base URL when Jira integration is enabled.";
     }
-    if (answers.enableJira && !answers.jiraToken?.trim()) {
-        return "setup requires a Jira token when Jira integration is enabled.";
+    if (answers.enableJira && !answers.jiraMcpUrl?.trim()) {
+        return "setup requires a Jira MCP URL when Jira integration is enabled.";
+    }
+    if (answers.enableJira && !answers.jiraUsername?.trim()) {
+        return "setup requires a Jira username when Jira integration is enabled.";
+    }
+    if (answers.enableJira && !answers.jiraPersonalToken?.trim()) {
+        return "setup requires a Jira personal token when Jira integration is enabled.";
     }
     return undefined;
 }
@@ -626,11 +1037,19 @@ function buildSetupConfig(answers) {
     config.jira.enabled = answers.enableJira;
     if (answers.enableJira) {
         config.jira.baseUrl = answers.jiraBaseUrl ?? config.jira.baseUrl;
-        config.jira.authType = "bearer";
-        if (answers.jiraToken) {
-            config.jira.bearerToken = answers.jiraToken;
-        }
-        config.jira.httpHeaders = {};
+        if (answers.jiraMcpUrl) {
+            config.jira.mcpUrl = answers.jiraMcpUrl;
+        }
+        config.jira.authType = "http_headers";
+        config.jira.httpHeaders = {
+            "X-Atlassian-Jira-Url": answers.jiraBaseUrl ?? config.jira.baseUrl,
+            "X-Atlassian-Username": answers.jiraUsername ?? "",
+            "X-Atlassian-Jira-Personal-Token": answers.jiraPersonalToken ?? ""
+        };
+        delete config.jira.bearerToken;
+        delete config.jira.username;
+        delete config.jira.apiToken;
+        delete config.jira.password;
     }
     return JSON.stringify(config, null, 2);
 }
@@ -839,20 +1258,9 @@ async function runQuickDoctor(configPath = resolveDefaultConfigPath()) {
         });
     }
     if (config.jira.enabled) {
-        if (!config.jira.baseUrl?.trim() || /jira\.example\.com/i.test(config.jira.baseUrl)) {
-            blocking.push({
-                code: "jira_base_url_missing",
-                message: "Jira integration is enabled, but Jira base URL is missing or still using the placeholder value.",
-                fix: "Rerun `optimus setup` and provide a real Jira base URL."
-            });
-            next.add("optimus setup");
-        }
-        if (!config.jira.bearerToken?.trim()) {
-            blocking.push({
-                code: "jira_token_missing",
-                message: "Jira integration is enabled, but Jira token is missing.",
-                fix: "Rerun `optimus setup` and provide a Jira token."
-            });
+        const jiraIssues = resolveJiraQuickDoctorIssues(config.jira);
+        blocking.push(...jiraIssues);
+        if (jiraIssues.length > 0) {
             next.add("optimus setup");
         }
     }
@@ -890,7 +1298,18 @@ async function runSetup(args) {
     if (!inspection.ok) {
         throw new Error(`Repository path is not usable: ${normalizedRepoPath} (${inspection.reason ?? "unknown"})`);
     }
-    const previewExecutionPlan = describeRepositoryExecutionPlan({ executionMode: "copy" }, inspection);
+    const preflightConfig = configExists ? await loadConfig(configPath) : buildDefaultConfig();
+    const preflightStore = new SQLiteTaskStore(preflightConfig.storage.rootDir);
+    await preflightStore.init();
+    const existingRepositories = await preflightStore.listRepositoryRoots();
+    const aliasConflict = existingRepositories.find((repository) => repository.alias === answers.repoAlias && repository.path !== normalizedRepoPath);
+    if (aliasConflict) {
+        throw new Error(`Repository alias already exists for another path: ${answers.repoAlias} -> ${aliasConflict.path}. `
+            + "Use `optimus repo update` or `optimus repo remove` before re-running setup.");
+    }
+    const existingRepository = existingRepositories.find((repository) => repository.path === normalizedRepoPath);
+    const resolvedExecutionMode = existingRepository?.executionMode ?? describeRepositoryExecutionPlan({ executionMode: "copy" }, inspection).resolvedDefaultMode;
+    const previewExecutionPlan = describeRepositoryExecutionPlan({ executionMode: resolvedExecutionMode }, inspection);
     const reviewSystem = await detectRepositoryReviewSystem(normalizedRepoPath, inspection);
     await mkdir(dirname(configPath), { recursive: true });
     await writeFile(configPath, `${buildSetupConfig({ ...answers, repoPath: normalizedRepoPath })}\n`, "utf8");
@@ -902,14 +1321,10 @@ async function runSetup(args) {
     const config = await loadConfig(configPath);
     const store = new SQLiteTaskStore(config.storage.rootDir);
     await store.init();
-    const existingRepositories = await store.listRepositoryRoots();
-    for (const repository of existingRepositories) {
-        await store.removeRepositoryRoot(repository.path);
-    }
     await store.addRepositoryRoot({
         path: normalizedRepoPath,
         alias: answers.repoAlias,
-        executionMode: previewExecutionPlan.resolvedDefaultMode
+        executionMode: resolvedExecutionMode
     });
     const doctorQuick = await runQuickDoctor(configPath);
     const codexAuth = new CodexAuthResolver(config).resolve().diagnostics;
@@ -922,7 +1337,7 @@ async function runSetup(args) {
             path: normalizedRepoPath,
             alias: answers.repoAlias,
             workspaceKind: previewExecutionPlan.workspaceKind,
-            executionMode: previewExecutionPlan.resolvedDefaultMode,
+            executionMode: resolvedExecutionMode,
             reviewSystem
         },
         deliveryChannels: config.delivery.channels,
@@ -1112,6 +1527,9 @@ function parseArgs(argv) {
     }
     return parsed;
 }
+function parsedCommandHasHelp(argv) {
+    return argv.some((token) => token === "-h" || token === "--help");
+}
 async function main() {
     const argv = process.argv.slice(2);
     const [firstArg, ...rest] = argv;
@@ -1126,6 +1544,12 @@ async function main() {
                 : firstArg;
     const commandArgs = rest;
     if (command === "help") {
+        const requestedCommand = commandArgs[0]?.trim();
+        if (requestedCommand) {
+            console.log(renderCommandHelp(requestedCommand) ?? renderCliHelp());
+            process.exitCode = renderCommandHelp(requestedCommand) ? 0 : 1;
+            return;
+        }
         console.log(renderCliHelp());
         return;
     }
@@ -1133,6 +1557,17 @@ async function main() {
         console.log(await readPackageVersion());
         return;
     }
+    if (parsedCommandHasHelp(commandArgs)) {
+        if (command === "repo") {
+            const repoSubcommand = commandArgs.find((token) => !token.startsWith("--"))?.trim();
+            console.log(renderCommandHelp("repo") ?? renderCliHelp());
+            process.exitCode = repoSubcommand && !["add", "remove", "update", "list", "doctor"].includes(repoSubcommand) ? 1 : 0;
+            return;
+        }
+        console.log(renderCommandHelp(command) ?? renderCliHelp());
+        process.exitCode = renderCommandHelp(command) ? 0 : 1;
+        return;
+    }
     if (command === "upgrade") {
         const args = parseArgs(commandArgs);
         const currentVersion = await readPackageVersion();
@@ -1187,6 +1622,10 @@ async function main() {
         process.exitCode = result.doctorQuick.summary === "blocked" ? 1 : 0;
         return;
     }
+    if (mapJiraCommand(command)) {
+        process.exitCode = await forwardJiraCliCommand(command, commandArgs);
+        return;
+    }
     const parsedCommandArgs = parseArgs(commandArgs);
     if (command === "doctor" && parsedCommandArgs.quick === "true") {
         const result = await runQuickDoctor();
@@ -1205,7 +1644,7 @@ async function main() {
     }
     catch (error) {
         if (error?.code === "ENOENT") {
-            console.error(`Config file not found at ${resolveDefaultConfigPath()}. Run \`optimus setup\` first.`);
+            console.error("Configuration is missing. Run `optimus setup` first.");
             process.exitCode = 1;
             return;
         }