rkb-cli 0.3.0-beta.1

package/README.md

@@ -0,0 +1,18 @@
+# rkb-cli
+
+Requires Node.js 20 or later. Run `rkb --help` for usage.
+
+Run `rkb login` to authorize the official Alibaba Cloud CLI OAuth application and obtain temporary STS credentials. Requires `aliyun >= 3.3.0`; no manual AK/SK is needed. Set `RKB_EXTERNAL_ALIYUN_CLI` only if the binary is not on PATH. Credentials are stored in `~/.rkb-external/aliyun/config.json` with owner-only file permissions. Use `--force` to authorize again. Run `rkb logout` to revoke the refresh token and remove this profile, or `logout --local` for local cleanup. POP APIs must enable AccessKey authentication and authorize the caller through RAM.
+
+Configuration: `~/.rkb-external/config.yaml`; environment prefix: `RKB_EXTERNAL_ENV_`.
+
+Available commands:
+
+- `rkb doc`
+- `rkb doc publish`
+- `rkb login`
+- `rkb logout`
+- `rkb space`
+- `rkb space list`
+- `rkb space use`
+- `rkb whoami`

package/bin/run.js

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

package/edition.json

@@ -0,0 +1,20 @@
+{
+  "edition": "external",
+  "features": [
+    "auth.aliyun",
+    "identity",
+    "space.list",
+    "space.use",
+    "doc.publish"
+  ],
+  "commands": [
+    "doc",
+    "doc:publish",
+    "login",
+    "logout",
+    "space",
+    "space:list",
+    "space:use",
+    "whoami"
+  ]
+}

package/lib/adapters/aliyun/official-cli.js

@@ -0,0 +1,338 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import OpenApiClient, { Config, Params, OpenApiRequest, } from "@alicloud/openapi-client";
+import { RuntimeOptions } from "@alicloud/tea-util";
+import { getConfigDir } from "../../config/index.js";
+import { CapabilityError } from "../../core/result.js";
+const profileName = "rkb-external";
+const oauthEndpoint = "https://oauth.aliyun.com/v1";
+// Used only to refresh tokens issued by the official CLI's own login flow.
+const officialClientId = "4038181954557748008";
+const Client = (typeof OpenApiClient === "function"
+    ? OpenApiClient
+    : OpenApiClient
+        .default);
+function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new CapabilityError("ALIYUN_INVALID_RESPONSE", "Alibaba Cloud returned an invalid response.");
+    return value;
+}
+function required(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw new CapabilityError("ALIYUN_INVALID_RESPONSE", "Alibaba Cloud returned incomplete credentials or identity.");
+    return value;
+}
+function loginRequired() {
+    return new CapabilityError("ALIYUN_LOGIN_REQUIRED", "Run rkb login to create or renew the external Alibaba Cloud login.");
+}
+// Do not pass ambient AK/SK or a different account's profile to the login process.
+export function officialCliEnvironment(source) {
+    return Object.fromEntries(Object.entries(source).filter(([key]) => !/^(ALIBABA_CLOUD|ALIBABACLOUD|ALICLOUD)_(ACCESS_KEY|SECURITY_TOKEN|PROFILE|REGION|ENDPOINT|STS_|BEARER_|OIDC_|ROLE_|CREDENTIALS_URI|EXTERNAL_)/.test(key) &&
+        !/^(ACCESS_KEY_ID|ACCESS_KEY_SECRET|SECURITY_TOKEN|REGION_ID|REGION)$/.test(key)));
+}
+export const runOfficialCli = (args, options) => new Promise((resolve, reject) => {
+    options.signal.throwIfAborted();
+    const child = spawn(process.env.RKB_EXTERNAL_ALIYUN_CLI || "aliyun", args, {
+        shell: false,
+        env: officialCliEnvironment(process.env),
+        stdio: ["pipe", "pipe", "pipe"],
+        signal: options.signal,
+        killSignal: "SIGKILL",
+    });
+    let stdout = "", stderr = "", pending = "";
+    const seen = new Set();
+    const authorizationLines = (chunk, final = false) => {
+        pending += chunk;
+        const lines = pending.split(/\r?\n/);
+        pending = final ? "" : lines.pop() || "";
+        for (const line of lines) {
+            const url = line.match(/https:\/\/signin\.aliyun\.com\/oauth2\/v1\/auth\?[^\s]+/)?.[0];
+            if (url && !seen.has(url)) {
+                seen.add(url);
+                options.onAuthorization?.(url);
+            }
+        }
+    };
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+        authorizationLines(chunk.toString());
+        if (stdout.length > 1024 * 1024)
+            child.kill("SIGKILL");
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+        if (stderr.length > 1024 * 1024)
+            child.kill("SIGKILL");
+    });
+    child.stdin.on("error", () => {
+        /* process errors are handled below */
+    });
+    // Region and language already have defaults in the isolated profile.
+    child.stdin.end("\n\n");
+    child.on("error", (error) => reject(options.signal.aborted
+        ? options.signal.reason
+        : new CapabilityError(error.code === "ENOENT"
+            ? "ALIYUN_CLI_NOT_FOUND"
+            : "ALIYUN_CLI_FAILED", error.code === "ENOENT"
+            ? "Install the official Alibaba Cloud CLI (aliyun >= 3.3.0), then run rkb login again."
+            : "The official Alibaba Cloud CLI could not run.")));
+    child.on("close", (code) => {
+        authorizationLines("", true);
+        if (options.signal.aborted) {
+            reject(options.signal.reason);
+            return;
+        }
+        if (code !== 0) {
+            // CLI stderr may contain tokens and signed URLs; never relay it verbatim.
+            const requestId = stderr.match(/request[_ ]?id["\s:=]+([A-Fa-f0-9-]{16,64})/i)?.[1];
+            reject(new CapabilityError("ALIYUN_CLI_FAILED", `Official Alibaba Cloud login failed${requestId ? `; RequestId: ${requestId}` : ""}. Check official-cli application authorization and try rkb login --force.`, requestId));
+            return;
+        }
+        resolve(stdout);
+    });
+});
+async function callerIdentity(credentials) {
+    const client = new Client(new Config({ endpoint: "sts.aliyuncs.com", ...credentials }));
+    const response = await client.callApi(new Params({
+        action: "GetCallerIdentity",
+        version: "2015-04-01",
+        protocol: "HTTPS",
+        pathname: "/",
+        method: "POST",
+        authType: "AK",
+        style: "RPC",
+        reqBodyType: "formData",
+        bodyType: "json",
+    }), new OpenApiRequest({}), new RuntimeOptions({
+        readTimeout: 15000,
+        connectTimeout: 15000,
+        autoretry: false,
+        maxAttempts: 1,
+    }));
+    return object(response.body);
+}
+export class OfficialCliSession {
+    configFile;
+    run;
+    request;
+    identify;
+    constructor(configFile = join(getConfigDir(), "aliyun", "config.json"), run = runOfficialCli, request = fetch, identify = callerIdentity) {
+        this.configFile = configFile;
+        this.run = run;
+        this.request = request;
+        this.identify = identify;
+    }
+    async load() {
+        let contents;
+        try {
+            contents = await readFile(this.configFile, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw new CapabilityError("ALIYUN_SESSION_INVALID", "Cannot read the external login. Run rkb logout --local, then rkb login.");
+        }
+        try {
+            const config = object(JSON.parse(contents));
+            const profile = Array.isArray(config.profiles)
+                ? config.profiles.find((p) => p?.name === profileName)
+                : undefined;
+            if (!profile ||
+                profile.mode !== "OAuth" ||
+                profile.oauth_site_type !== "CN")
+                throw loginRequired();
+            return { config, profile: object(profile) };
+        }
+        catch {
+            throw new CapabilityError("ALIYUN_SESSION_INVALID", "The external OAuth profile is invalid. Run rkb logout --local, then rkb login.");
+        }
+    }
+    async save(config, signal) {
+        signal.throwIfAborted();
+        await mkdir(dirname(this.configFile), { recursive: true, mode: 0o700 });
+        const temporary = `${this.configFile}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(config, null, 2) + "\n", {
+                mode: 0o600,
+                flag: "wx",
+            });
+            signal.throwIfAborted();
+            await rename(temporary, this.configFile);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async oauth(path, init, signal) {
+        let response;
+        try {
+            response = await this.request(`${oauthEndpoint}/${path}`, {
+                ...init,
+                method: "POST",
+                redirect: "error",
+                signal: AbortSignal.any([signal, AbortSignal.timeout(15000)]),
+            });
+        }
+        catch {
+            signal.throwIfAborted();
+            throw new CapabilityError("ALIYUN_OAUTH_REQUEST_FAILED", "Alibaba Cloud OAuth request failed. Check the network and retry.");
+        }
+        if (!response.ok)
+            throw new CapabilityError("ALIYUN_OAUTH_REJECTED", `Alibaba Cloud rejected credential ${path} (HTTP ${response.status}). Run rkb login --force; official-cli authorization is required.`);
+        if (path === "revoke")
+            return {};
+        try {
+            return object(await response.json());
+        }
+        catch {
+            throw new CapabilityError("ALIYUN_INVALID_RESPONSE", "Alibaba Cloud returned an invalid credential response.");
+        }
+    }
+    async get(signal = AbortSignal.timeout(30000)) {
+        signal.throwIfAborted();
+        const saved = await this.load();
+        if (!saved || !saved.profile.oauth_access_token)
+            throw loginRequired();
+        const { profile, config } = saved;
+        const now = Math.floor(Date.now() / 1000);
+        const credentials = () => ({
+            accessKeyId: required(profile.access_key_id),
+            accessKeySecret: required(profile.access_key_secret),
+            securityToken: required(profile.sts_token),
+            expiresAt: Number(profile.sts_expiration) * 1000,
+        });
+        if (Number(profile.sts_expiration) > now + 60 &&
+            profile.access_key_id &&
+            profile.access_key_secret &&
+            profile.sts_token)
+            return credentials();
+        if (!(Number(profile.oauth_access_token_expire) > now + 60)) {
+            if (!profile.oauth_refresh_token)
+                throw loginRequired();
+            const renewed = await this.oauth("token", {
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: required(profile.oauth_refresh_token),
+                    client_id: officialClientId,
+                }),
+            }, signal);
+            profile.oauth_access_token = required(renewed.access_token);
+            if (!(typeof renewed.expires_in === "number" && renewed.expires_in > 0))
+                throw new CapabilityError("ALIYUN_INVALID_RESPONSE", "Alibaba Cloud returned an invalid token expiry.");
+            profile.oauth_access_token_expire = now + renewed.expires_in;
+            if (renewed.refresh_token)
+                profile.oauth_refresh_token = required(renewed.refresh_token);
+            // Persist refresh-token rotation even if the following STS exchange fails.
+            await this.save(config, signal);
+        }
+        const exchanged = await this.oauth("exchange", {
+            headers: {
+                Authorization: `Bearer ${required(profile.oauth_access_token)}`,
+                "Content-Type": "application/json",
+                "User-Agent": "aliyun-cli",
+            },
+        }, signal);
+        // The live exchange endpoint returns PascalCase; also accept camelCase.
+        const expiration = Date.parse(required(exchanged.Expiration ?? exchanged.expiration));
+        if (!Number.isFinite(expiration) || expiration <= Date.now() + 60000)
+            throw new CapabilityError("ALIYUN_INVALID_RESPONSE", "Alibaba Cloud returned expired STS credentials.");
+        profile.access_key_id = required(exchanged.AccessKeyId ?? exchanged.accessKeyId);
+        profile.access_key_secret = required(exchanged.AccessKeySecret ?? exchanged.accessKeySecret);
+        profile.sts_token = required(exchanged.SecurityToken ?? exchanged.securityToken);
+        profile.sts_expiration = Math.floor(expiration / 1000);
+        await this.save(config, signal);
+        return credentials();
+    }
+    async login(options) {
+        const saved = await this.load();
+        const reused = !options.force && Boolean(saved?.profile.oauth_access_token);
+        if (!reused) {
+            const version = await this.run(["version"], { signal: options.signal });
+            const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)$/);
+            if (!match ||
+                Number(match[1]) < 3 ||
+                (Number(match[1]) === 3 && Number(match[2]) < 3))
+                throw new CapabilityError("ALIYUN_CLI_VERSION", "Official Alibaba Cloud CLI 3.3.0 or later is required.");
+            if (!saved)
+                await this.save({
+                    current: profileName,
+                    profiles: [
+                        {
+                            name: profileName,
+                            mode: "OAuth",
+                            oauth_site_type: "CN",
+                            region_id: "cn-hangzhou",
+                            output_format: "json",
+                            language: "en",
+                        },
+                    ],
+                }, options.signal);
+            await this.run([
+                "configure",
+                "--mode",
+                "OAuth",
+                "--oauth-site-type",
+                "CN",
+                "--profile",
+                profileName,
+                "--config-path",
+                this.configFile,
+            ], options);
+        }
+        const credentials = await this.get(options.signal);
+        let identity;
+        try {
+            identity = await this.identify(credentials);
+        }
+        catch {
+            options.signal.throwIfAborted();
+            throw new CapabilityError("ALIYUN_IDENTITY_FAILED", "STS identity verification failed. Check the network or run rkb login --force.");
+        }
+        options.signal.throwIfAborted();
+        return {
+            identity: {
+                subject: required(identity.PrincipalId),
+                type: required(identity.IdentityType),
+                accountId: required(identity.AccountId),
+                userId: required(identity.PrincipalId),
+                name: required(identity.Arn),
+            },
+            expiresAt: new Date(credentials.expiresAt).toISOString(),
+            reused,
+        };
+    }
+    async logout(options) {
+        options.signal.throwIfAborted();
+        const saved = options.local ? undefined : await this.load();
+        let revocation = options.local ? "skipped" : "not_needed";
+        if (saved) {
+            const refresh = saved.profile.oauth_refresh_token;
+            if (refresh) {
+                await this.oauth("revoke", {
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: new URLSearchParams({
+                        token: required(refresh),
+                        token_type_hint: "refresh_token",
+                        client_id: officialClientId,
+                    }),
+                }, options.signal);
+                revocation = "confirmed";
+            }
+            else
+                revocation = "no_refresh_token";
+        }
+        options.signal.throwIfAborted();
+        try {
+            await rm(this.configFile);
+            return { cleared: true, revocation };
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { cleared: false, revocation };
+            throw new CapabilityError("ALIYUN_LOGOUT_FAILED", "Cannot remove the external login file. Retry rkb logout --local.");
+        }
+    }
+}

package/lib/adapters/pop/context.js

@@ -0,0 +1,34 @@
+import { getConfigValue } from "../../config/index.js";
+import { runtimeProfile } from "../../runtime/profile.js";
+import { CapabilityError } from "../../core/result.js";
+import { field, requiredString } from "./transport.js";
+export class PopContext {
+    api;
+    selectedTenant;
+    initial;
+    constructor(api, selectedTenant = () => String(getConfigValue(runtimeProfile.tenantKey) ?? "").trim()) {
+        this.api = api;
+        this.selectedTenant = selectedTenant;
+    }
+    initialState() {
+        // No client tenant hint: this must reflect the backend's identity mapping.
+        return (this.initial ??= this.api.call("GetInitialState"));
+    }
+    async mappedTenant() {
+        // This branch returns currentTenantCode=null when no tenant hint is supplied.
+        // Its tenants array contains exactly the identity-mapped tenant.
+        const tenants = field(await this.initialState(), "tenants");
+        if (!Array.isArray(tenants) || tenants.length !== 1)
+            throw new CapabilityError("POP_TENANT_AMBIGUOUS", "POP did not identify a unique account tenant; pipeline tenant selection needs backend support.");
+        return requiredString(tenants[0], "code");
+    }
+    async tenant() {
+        return this.selectedTenant() || (await this.mappedTenant());
+    }
+    async assertBranchTenant() {
+        const mapped = await this.mappedTenant();
+        const selected = this.selectedTenant();
+        if (selected && mapped !== selected)
+            throw new CapabilityError("POP_TENANT_UNSUPPORTED", `This POP backend runs pipelines in tenant '${mapped}', but '${selected}' is selected. Cross-tenant pipelines require backend support.`);
+    }
+}

package/lib/adapters/pop/doc-publish.js

@@ -0,0 +1,7 @@
+import { createTransport } from "./transport.js";
+import { PopContext } from "./context.js";
+import { PopPipelineStarter, createPipelineService } from "./pipeline.js";
+export function createService() {
+    const api = createTransport();
+    return createPipelineService(new PopPipelineStarter(api, new PopContext(api), "PublishBranch"));
+}

package/lib/adapters/pop/identity.js

@@ -0,0 +1,31 @@
+import { CapabilityError } from "../../core/result.js";
+import { createTransport, field, requiredString, } from "./transport.js";
+export class PopIdentity {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    async whoami() {
+        try {
+            const state = await this.api.call("GetInitialState");
+            const user = field(state, "userInfo");
+            const email = field(user, "email");
+            return {
+                success: true,
+                message: "Credentials validated",
+                data: {
+                    name: requiredString(user, "name"),
+                    ...(typeof email === "string" ? { email } : {}),
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                code: error instanceof CapabilityError ? error.code : "POP_IDENTITY_FAILED",
+            };
+        }
+    }
+}
+export const createService = () => new PopIdentity(createTransport());

package/lib/adapters/pop/pipeline.js

@@ -0,0 +1,50 @@
+import { CapabilityError } from "../../core/result.js";
+import { PipelineService } from "../../features/doc/pipeline/service.js";
+import { getGitBranch, getPipelineGitIssues } from "../../lib/git-project.js";
+import { resourceContext } from "../../core/context.js";
+import { field } from "./transport.js";
+export class PopPipelineStarter {
+    api;
+    context;
+    action;
+    constructor(api, context, action) {
+        this.api = api;
+        this.context = context;
+        this.action = action;
+    }
+    async start(input) {
+        if (input.workflowInstanceId !== undefined)
+            throw new CapabilityError("POP_WORKFLOW_UNSUPPORTED", "This POP backend does not accept WORKFLOW_INSTANCE_ID. Unset it before starting a pipeline.");
+        await this.context.assertBranchTenant();
+        const result = await this.api.call(this.action, {
+            SpaceCode: input.spaceCode,
+            BranchName: input.branchName,
+        });
+        const rawId = field(result, "pipelineInstanceId");
+        const pipelineId = typeof rawId === "number" ||
+            (typeof rawId === "string" && /^[0-9]+$/.test(rawId))
+            ? Number(rawId)
+            : NaN;
+        if (!Number.isSafeInteger(pipelineId) || pipelineId <= 0)
+            throw new CapabilityError("POP_INVALID_RESPONSE", "POP returned an invalid pipelineInstanceId.");
+        // A POP endpoint is not a console URL. Do not fabricate or open a pipeline URL.
+        return { pipelineId };
+    }
+}
+export function createPipelineService(api) {
+    const context = resourceContext();
+    return new PipelineService(api, {
+        getProject: () => {
+            const branchName = getGitBranch();
+            const spaceCode = context.getSpace();
+            return branchName && spaceCode
+                ? { tenantCode: "", spaceCode, branchName }
+                : null;
+        },
+        getSpace: context.getSpace,
+        requireSpace: true,
+        bin: context.bin,
+        getGitIssues: getPipelineGitIssues,
+        workflowInstanceId: process.env.WORKFLOW_INSTANCE_ID,
+    });
+}

package/lib/adapters/pop/sandbox-sts.js

@@ -0,0 +1,19 @@
+import { CapabilityError } from "../../core/result.js";
+/** Only the platform's explicit sandbox mode can select environment credentials. */
+export function readSandboxStsCredentials(env = process.env, now = Date.now()) {
+    if (env.RKB_POP_AUTH_MODE !== "sandbox-sts")
+        return undefined;
+    const accessKeyId = env.ALIBABA_CLOUD_ACCESS_KEY_ID?.trim();
+    const accessKeySecret = env.ALIBABA_CLOUD_ACCESS_KEY_SECRET?.trim();
+    const securityToken = env.ALIBABA_CLOUD_SECURITY_TOKEN?.trim();
+    if (!accessKeyId || !accessKeySecret || !securityToken)
+        throw new CapabilityError("SANDBOX_STS_MISSING", "Sandbox STS credentials are incomplete. Ask the sandbox platform to supply fresh credentials.");
+    // Some AKless providers expose only the tuple. Do not invent its expiration.
+    const expiration = env.RKB_POP_STS_EXPIRES_AT;
+    const expiresAt = expiration === undefined ? undefined : Date.parse(expiration);
+    if (expiresAt !== undefined && !Number.isFinite(expiresAt))
+        throw new CapabilityError("SANDBOX_STS_INVALID_EXPIRATION", "Sandbox STS expiration is invalid. Ask the sandbox platform to supply fresh credentials.");
+    if (expiresAt !== undefined && expiresAt <= now + 60000)
+        throw new CapabilityError("SANDBOX_STS_EXPIRED", "Sandbox STS credentials have expired or are about to expire. Ask the sandbox platform to renew them.");
+    return { accessKeyId, accessKeySecret, securityToken, expiresAt };
+}

package/lib/adapters/pop/space-read.js

@@ -0,0 +1,67 @@
+import { SpaceReadService } from "../../features/space/read/service.js";
+import { resourceContext } from "../../core/context.js";
+import { CapabilityError } from "../../core/result.js";
+import { createTransport, field, requiredString, } from "./transport.js";
+import { PopContext } from "./context.js";
+function space(value) {
+    const result = {
+        code: requiredString(value, "spaceCode"),
+        name: requiredString(value, "name"),
+    };
+    for (const key of [
+        "tenantCode",
+        "description",
+        "defaultBranch",
+        "defaultLanguage",
+        "domain",
+    ]) {
+        const item = field(value, key);
+        if (typeof item === "string")
+            result[key] = item;
+    }
+    return result;
+}
+export class PopSpaceReader {
+    api;
+    context;
+    constructor(api, context) {
+        this.api = api;
+        this.context = context;
+    }
+    async listSpaces() {
+        const tenantCode = await this.context.tenant();
+        const spaces = [];
+        const seen = new Set();
+        let nextToken;
+        do {
+            const page = await this.api.call("ListSpaces", {
+                TenantCode: tenantCode,
+                MaxResults: 100,
+                NextToken: nextToken,
+            });
+            const items = field(page, "spaces");
+            if (!Array.isArray(items))
+                throw new CapabilityError("POP_INVALID_RESPONSE", "POP ListSpaces response has no spaces array.");
+            spaces.push(...items.map(space));
+            const token = field(page, "nextToken");
+            if (token !== undefined && token !== null && typeof token !== "string")
+                throw new CapabilityError("POP_INVALID_RESPONSE", "POP returned an invalid pagination token.");
+            nextToken = typeof token === "string" && token ? token : undefined;
+            if (nextToken && seen.has(nextToken))
+                throw new CapabilityError("POP_PAGINATION_LOOP", "POP returned a repeated pagination token.");
+            if (nextToken)
+                seen.add(nextToken);
+        } while (nextToken);
+        return spaces;
+    }
+    async getSpace(code) {
+        return space(await this.api.call("DescribeSpace", {
+            TenantCode: await this.context.tenant(),
+            SpaceCode: code,
+        }));
+    }
+}
+export function createService() {
+    const api = createTransport();
+    return new SpaceReadService(new PopSpaceReader(api, new PopContext(api)), resourceContext());
+}