@helixlife-ai/xiantao 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# xt
+
+CLI for Xiantao bioinformatics tools.
+
+Install with `npm i -g @helixlife-ai/xiantao` and run it as `xt`.
+
+`tool` is the primary product topic for bioinformatics tools. `plot` is kept as a compatibility entrypoint for the current command set and prints a migration warning when executed.
+
+`--profile` is the primary profile selector for token lookup and config isolation, for example `default` or `openclaw`. `--agent` is kept as a compatibility alias.
+
+`login`, `status`, and `logout` are the primary auth entrypoints. `auth ...` is kept as a compatibility topic and prints a migration warning when executed.
+
+## Main Flows
+
+### First Use
+
+```bash
+xt login
+xt tool search violin
+xt tool inspect violin_flat
+xt tool run violin_flat ./data.xlsx
+```
+
+`xt login` is used for upload-related APIs. If the stored Xiantao web token is missing or expired for `tool search`, `tool inspect`, or `tool run`, run `xt tool login` under the same profile.
+
+### Interactive Tool Run
+
+```bash
+xt tool run --interactive
+```
+
+This starts a menu-driven path for choosing a tool, selecting demo data or a local file, filling dynamic `args_main`, and optionally downloading generated outputs.
+
+### Agent Automation
+
+```bash
+xt tool exec violin_flat --file ./data.xlsx --profile openclaw --json
+```
+
+For machine callers, use `xt tool exec`, keep `--json`, pass an explicit profile with `--profile`, and avoid interactive-only flows.
+
+## Command Groups
+
+### Auth
+
+- `xt login`
+- `xt status`
+- `xt logout`
+- `xt tool login`
+
+### Tool Run
+
+- `xt tool search`
+- `xt tool inspect`
+- `xt tool run`
+- `xt tool exec`
+- `xt tool download`
+
+### Tool Debug
+
+- `xt tool resolve`
+- `xt tool menu`
+- `xt tool menus`
+- `xt tool fetch-all`
+
+## Notes
+
+For the common Xiantao tool product, `tool search`, `tool inspect`, `tool run`, `tool resolve`, and `tool menu` default `toolProductUuid` to `c0b6febb-52dd-4525-970a-61bbe9e263ff`. You can override it with `--toolProductUuid`, `XIANTAO_TOOL_PRODUCT_UUID`, or `~/.config/xtz/config.json` under `xiantao.toolProductUuid`.
+
+`xt tool search <keyword>` searches cached or remote tool menus by tool id, title, path, and route. `xt tool inspect <tool_id>` prints resolved metadata together with the dynamic `args_main` schema used by the tool. `xt tool run <tool_id>` runs a Xiantao bioinformatics tool. `xt tool resolve <tool_id>` remains available as the low-level UUID and route lookup. `--demo` reuses the demo file metadata returned by `tool fetch-all`; otherwise `tool run` uploads the local file first and therefore also needs `xt login`.
+
+`xt tool run <tool_id> ... --interactive` prompts for dynamic `args_main` values before the final submit, prints reusable `--set` flags, and supports `<` for the previous item plus `/skip` for the current section.
+
+When resolving tools from `--toolProductUuid`, the CLI caches the `/tool/menus?is_all=1` result locally for 12 hours per `profile + toolProductUuid` to avoid repeated full-menu fetches.
+
+## Development
+
+```bash
+npm install
+npm run build
+node ./bin/run.js --help
+```
+
+## Autocomplete
+
+oclif supports shell completion through `@oclif/plugin-autocomplete`.
+
+```bash
+xt autocomplete zsh
+xt autocomplete bash
+```

package/bin/dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/base-command.js

@@ -0,0 +1,40 @@
+import { Command } from '@oclif/core';
+import { XtzError } from './lib/errors.js';
+import { resolveAgent } from './lib/storage.js';
+export class XtzCommand extends Command {
+    async getProfile(profileFlag) {
+        return resolveAgent(profileFlag);
+    }
+    async getAgent(agentFlag) {
+        return this.getProfile(agentFlag);
+    }
+    print(flags, data, text) {
+        if (flags.json) {
+            this.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        this.log(text);
+    }
+    async catch(error) {
+        if (error instanceof XtzError) {
+            this.error(error.message, { exit: 1 });
+        }
+        throw error;
+    }
+    warnIfLegacyPlotCommand() {
+        if (!this.id?.startsWith('plot:') || this.argv.includes('--json')) {
+            return;
+        }
+        const command = this.id.replaceAll(':', ' ');
+        const replacement = command.replace(/^plot\b/, 'tool');
+        this.warn(`\`xt ${command}\` 已兼容保留，建议改用 \`xt ${replacement}\``);
+    }
+    warnIfLegacyAuthCommand() {
+        if (!this.id?.startsWith('auth:') || this.argv.includes('--json')) {
+            return;
+        }
+        const command = this.id.replaceAll(':', ' ');
+        const replacement = command.replace(/^auth /, '');
+        this.warn(`\`xt ${command}\` 已兼容保留，建议改用 \`xt ${replacement}\``);
+    }
+}

package/dist/commands/auth/login.js

@@ -0,0 +1,35 @@
+import { Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { fetchAuthLink } from '../../lib/auth.js';
+import { globalFlags } from '../../lib/flags.js';
+import { openUrl } from '../../lib/open-url.js';
+import { getTokenPath, saveToken } from '../../lib/storage.js';
+export default class AuthLogin extends XtzCommand {
+    static description = 'Get an authorization link for the current profile and save the token locally';
+    static flags = {
+        ...globalFlags,
+        open: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Open the authorization link in the browser',
+        }),
+    };
+    async run() {
+        this.warnIfLegacyAuthCommand();
+        const { flags } = await this.parse(AuthLogin);
+        const agent = await this.getProfile(flags.profile);
+        const { linkUrl, tokenKey } = await fetchAuthLink(agent);
+        const tokenPath = await saveToken(agent, tokenKey);
+        const opened = flags.open ? await openUrl(linkUrl) : false;
+        this.print(flags, {
+            agent,
+            browser_opened: opened,
+            link_url: linkUrl,
+            token_path: tokenPath,
+        }, [
+            `profile: ${agent}`,
+            `token: ${getTokenPath(agent)}`,
+            opened ? '浏览器已打开授权链接，请完成授权后运行 `xt status`。' : `请在浏览器中打开: ${linkUrl}`,
+        ].join('\n'));
+    }
+}

package/dist/commands/auth/logout.js

@@ -0,0 +1,20 @@
+import { XtzCommand } from '../../base-command.js';
+import { globalFlags } from '../../lib/flags.js';
+import { deleteToken, getTokenPath } from '../../lib/storage.js';
+export default class AuthLogout extends XtzCommand {
+    static description = 'Delete the stored token for the current profile';
+    static flags = {
+        ...globalFlags,
+    };
+    async run() {
+        this.warnIfLegacyAuthCommand();
+        const { flags } = await this.parse(AuthLogout);
+        const agent = await this.getProfile(flags.profile);
+        const removed = await deleteToken(agent);
+        this.print(flags, {
+            agent,
+            removed,
+            token_path: getTokenPath(agent),
+        }, removed ? `已删除 token: ${getTokenPath(agent)}` : `未找到 token: ${getTokenPath(agent)}`);
+    }
+}

package/dist/commands/auth/status.js

@@ -0,0 +1,22 @@
+import { XtzCommand } from '../../base-command.js';
+import { checkToken } from '../../lib/auth.js';
+import { globalFlags } from '../../lib/flags.js';
+import { getTokenPath, requireToken } from '../../lib/storage.js';
+export default class AuthStatus extends XtzCommand {
+    static description = 'Check whether the current profile token is authorized';
+    static flags = {
+        ...globalFlags,
+    };
+    async run() {
+        this.warnIfLegacyAuthCommand();
+        const { flags } = await this.parse(AuthStatus);
+        const agent = await this.getProfile(flags.profile);
+        const token = await requireToken(agent);
+        await checkToken(agent, token);
+        this.print(flags, {
+            agent,
+            authorized: true,
+            token_path: getTokenPath(agent),
+        }, `profile: ${agent}\nauthorized: true\ntoken: ${getTokenPath(agent)}`);
+    }
+}

package/dist/commands/login.js

@@ -0,0 +1,3 @@
+import AuthLogin from './auth/login.js';
+export default class Login extends AuthLogin {
+}

package/dist/commands/logout.js

@@ -0,0 +1,3 @@
+import AuthLogout from './auth/logout.js';
+export default class Logout extends AuthLogout {
+}

package/dist/commands/plot/download.js

@@ -0,0 +1,31 @@
+import { Args, Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { downloadToPath } from '../../lib/download.js';
+export default class PlotDownload extends XtzCommand {
+    static description = 'Download a generated tool result URL to a local file';
+    static args = {
+        url: Args.string({
+            description: 'Direct file URL returned by a tool command',
+            required: true,
+        }),
+    };
+    static flags = {
+        json: Flags.boolean({
+            default: false,
+            description: 'Output JSON',
+        }),
+        output: Flags.string({
+            char: 'o',
+            description: 'Destination path; defaults to the file name inferred from the URL',
+        }),
+    };
+    async run() {
+        this.warnIfLegacyPlotCommand();
+        const { args, flags } = await this.parse(PlotDownload);
+        const filePath = await downloadToPath(args.url, flags.output);
+        this.print(flags, {
+            path: filePath,
+            url: args.url,
+        }, filePath);
+    }
+}

package/dist/commands/plot/fetch-all.js

@@ -0,0 +1,47 @@
+import { Args, Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { globalFlags } from '../../lib/flags.js';
+import { buildArgsMainFromSchema } from '../../lib/plot-schema.js';
+import { getXiantaoAuthContext } from '../../lib/xiantao-auth.js';
+import { fetchAllPlotArgs } from '../../lib/xiantao.js';
+export default class PlotFetchAll extends XtzCommand {
+    static description = 'Fetch raw dynamic args for a Xiantao tool via public.args.fetch-all';
+    static args = {
+        moduleId: Args.string({
+            description: 'Tool id, e.g. violin_flat',
+            required: true,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        token: Flags.string({
+            description: 'Bearer token for api.helixlife.net xiantao APIs; falls back to XIANTAO_TOKEN or the stored Xiantao web token',
+        }),
+        uuid: Flags.string({
+            description: 'Tool UUID used in the public.args.fetch-all payload',
+            required: true,
+        }),
+    };
+    async run() {
+        this.warnIfLegacyPlotCommand();
+        const { args, flags } = await this.parse(PlotFetchAll);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getXiantaoAuthContext(agent, flags.token);
+        const result = await fetchAllPlotArgs(auth, {
+            moduleId: args.moduleId,
+            uuid: flags.uuid,
+        });
+        const argsMainDefaults = buildArgsMainFromSchema(result.args_main);
+        const output = {
+            agent,
+            args_data: result.args_data ?? [],
+            args_main: result.args_main ?? [],
+            args_main_defaults: argsMainDefaults,
+            duid: result.id?.duid ?? '',
+            module_id: args.moduleId,
+            notice: result.notice ?? '',
+            uuid: flags.uuid,
+        };
+        this.print(flags, output, JSON.stringify(output, null, 2));
+    }
+}

package/dist/commands/plot/login.js

@@ -0,0 +1,27 @@
+import { XtzCommand } from '../../base-command.js';
+import { globalFlags } from '../../lib/flags.js';
+import { getXiantaoTokenPath } from '../../lib/storage.js';
+import { loginXiantao } from '../../lib/xiantao-auth.js';
+export default class PlotLogin extends XtzCommand {
+    static description = 'Sign in to Xiantao web APIs for the current profile and save the returned token locally';
+    static flags = {
+        ...globalFlags,
+    };
+    async run() {
+        this.warnIfLegacyPlotCommand();
+        const { flags } = await this.parse(PlotLogin);
+        const agent = await this.getProfile(flags.profile);
+        const result = await loginXiantao(agent);
+        this.print(flags, {
+            agent,
+            browser_opened: result.browserOpened,
+            callback_url: result.callbackUrl,
+            jump_url: result.jumpUrl,
+            token_path: result.tokenPath,
+        }, [
+            `profile: ${agent}`,
+            `xiantao_token: ${getXiantaoTokenPath(agent)}`,
+            result.browserOpened ? '仙桃网页登录成功，token 已保存。' : `请在浏览器中打开: ${result.jumpUrl}`,
+        ].join('\n'));
+    }
+}

package/dist/commands/plot/menu.js

@@ -0,0 +1,37 @@
+import { Args, Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { globalFlags } from '../../lib/flags.js';
+import { resolveXiantaoToolProductUuid } from '../../lib/storage.js';
+import { getXiantaoAuthContext } from '../../lib/xiantao-auth.js';
+import { fetchToolMenu } from '../../lib/xiantao.js';
+export default class PlotMenu extends XtzCommand {
+    static description = 'Fetch Xiantao menu metadata for a tool menu UUID';
+    static args = {
+        menuUuid: Args.string({
+            description: 'Tool menu UUID from /tool/menus/:uuid',
+            required: true,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        token: Flags.string({
+            description: 'Bearer token for api.helixlife.net xiantao APIs; falls back to XIANTAO_TOKEN or the stored Xiantao web token',
+        }),
+        toolProductUuid: Flags.string({
+            description: 'tool_product_uuid used in the menu filter payload; defaults to the main Xiantao product UUID',
+        }),
+    };
+    async run() {
+        this.warnIfLegacyPlotCommand();
+        const { args, flags } = await this.parse(PlotMenu);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getXiantaoAuthContext(agent, flags.token);
+        const toolProductUuid = await resolveXiantaoToolProductUuid(flags.toolProductUuid);
+        const menu = await fetchToolMenu(auth, args.menuUuid, toolProductUuid);
+        this.print(flags, {
+            agent,
+            menu,
+            tool_product_uuid: toolProductUuid,
+        }, JSON.stringify(menu, null, 2));
+    }
+}

package/dist/commands/plot/menus.js

@@ -0,0 +1,31 @@
+import { Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { globalFlags } from '../../lib/flags.js';
+import { resolveXiantaoToolProductUuid } from '../../lib/storage.js';
+import { getXiantaoAuthContext } from '../../lib/xiantao-auth.js';
+import { fetchToolMenus } from '../../lib/xiantao.js';
+export default class PlotMenus extends XtzCommand {
+    static description = 'Fetch all Xiantao menu metadata for a tool product';
+    static flags = {
+        ...globalFlags,
+        token: Flags.string({
+            description: 'Bearer token for api.helixlife.net xiantao APIs; falls back to XIANTAO_TOKEN or the stored Xiantao web token',
+        }),
+        toolProductUuid: Flags.string({
+            description: 'tool_product_uuid used in the menu filter payload; defaults to the main Xiantao product UUID',
+        }),
+    };
+    async run() {
+        this.warnIfLegacyPlotCommand();
+        const { flags } = await this.parse(PlotMenus);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getXiantaoAuthContext(agent, flags.token);
+        const toolProductUuid = await resolveXiantaoToolProductUuid(flags.toolProductUuid);
+        const menus = await fetchToolMenus(auth, toolProductUuid);
+        this.print(flags, {
+            agent,
+            menus,
+            tool_product_uuid: toolProductUuid,
+        }, JSON.stringify(menus, null, 2));
+    }
+}

package/dist/commands/plot/resolve.js

@@ -0,0 +1,48 @@
+import { Args, Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { globalFlags } from '../../lib/flags.js';
+import { resolveXiantaoToolProductUuid } from '../../lib/storage.js';
+import { getXiantaoAuthContext } from '../../lib/xiantao-auth.js';
+import { resolveToolMenuByCode } from '../../lib/xiantao.js';
+export default class PlotResolve extends XtzCommand {
+    static description = 'Resolve a Xiantao tool id to its UUID and route';
+    static args = {
+        moduleId: Args.string({
+            description: 'Tool id, e.g. violin_flat',
+            required: true,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        token: Flags.string({
+            description: 'Bearer token for api.helixlife.net xiantao APIs; falls back to XIANTAO_TOKEN or the stored Xiantao web token',
+        }),
+        toolProductUuid: Flags.string({
+            description: 'tool_product_uuid from the /products/apply/:uuid URL; defaults to the main Xiantao product UUID',
+        }),
+    };
+    async run() {
+        this.warnIfLegacyPlotCommand();
+        const { args, flags } = await this.parse(PlotResolve);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getXiantaoAuthContext(agent, flags.token);
+        const toolProductUuid = await resolveXiantaoToolProductUuid(flags.toolProductUuid);
+        const resolved = await resolveToolMenuByCode(auth, toolProductUuid, args.moduleId);
+        this.print(flags, {
+            agent,
+            module_id: args.moduleId,
+            path: resolved.path,
+            route: resolved.route,
+            title: resolved.title,
+            tool_product_uuid: toolProductUuid,
+            uuid: resolved.uuid,
+        }, JSON.stringify({
+            module_id: args.moduleId,
+            path: resolved.path,
+            route: resolved.route,
+            title: resolved.title,
+            tool_product_uuid: toolProductUuid,
+            uuid: resolved.uuid,
+        }, null, 2));
+    }
+}