@sireai/optimus 0.1.2 → 0.1.3

package/dist/cli/optimus.js

@@ -28,12 +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");
@@ -131,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:",
-        "  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-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",
+        "  db-inspect            Show raw persisted task data",
         "",
         "Global options:",
         "  -h, --help            Show this help",
@@ -174,6 +177,242 @@ 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":
@@ -276,18 +515,27 @@ function isInteractiveSelfUpdatePromptAllowed() {
 async function promptForStartupSelfUpdate(currentVersion, latestVersion) {
     const rl = createInterface({ input, output });
     try {
-        console.log(`[optimus] update available ${currentVersion} -> ${latestVersion}.`);
-        console.log("1. Upgrade now and exit");
-        console.log("2. Continue with current version");
+        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("Select [1/2] (default 2): ")).trim().toLowerCase();
-            if (!answer || answer === "2" || answer === "c" || answer === "continue") {
-                return "continue";
+            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 to upgrade or 2 to continue.");
+            console.log("Invalid selection. Enter 1, 2, or 3.");
         }
     }
     finally {
@@ -324,6 +572,14 @@ async function maybeHandleStartupSelfUpdate(input) {
     if (!check.updateAvailable || !check.latestVersion) {
         return { handled: false };
     }
+    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\`.`);
@@ -341,7 +597,20 @@ async function maybeHandleStartupSelfUpdate(input) {
             latestVersion: check.latestVersion,
             choice
         });
-        if (choice === "continue") {
+        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 };
         }
     }
@@ -556,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,
@@ -573,7 +848,9 @@ async function promptSetupAnswers(defaults) {
             ...(feishuSecret ? { feishuSecret } : {}),
             enableJira,
             ...(jiraBaseUrl ? { jiraBaseUrl } : {}),
-            ...(jiraToken ? { jiraToken } : {})
+            ...(jiraMcpUrl ? { jiraMcpUrl } : {}),
+            ...(jiraUsername ? { jiraUsername } : {}),
+            ...(jiraPersonalToken ? { jiraPersonalToken } : {})
         };
     }
     finally {
@@ -618,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) {
@@ -685,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;
 }
@@ -752,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);
 }
@@ -1234,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;
@@ -1248,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;
     }
@@ -1255,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();