rkb-cli 0.3.0-beta.1

package/lib/features/doc/pipeline/service.js

@@ -0,0 +1,65 @@
+import { CapabilityError } from "../../../core/result.js";
+export class PipelineService {
+    api;
+    context;
+    constructor(api, context) {
+        this.api = api;
+        this.context = context;
+    }
+    async startPipeline() {
+        if (this.context.requireSpace && !this.context.getSpace())
+            return {
+                success: false,
+                code: "SPACE_NOT_SELECTED",
+                error: `No current space. Run '${this.context.bin} space use <spaceCode>' first.`,
+            };
+        const project = this.context.getProject();
+        if (!project)
+            return {
+                success: false,
+                code: "GIT_CONTEXT_MISSING",
+                error: "Not a supported Git repository. Run this command in a documentation repository with an origin remote.",
+            };
+        const space = this.context.getSpace();
+        if (space && space !== project.spaceCode)
+            return {
+                success: false,
+                code: "SPACE_MISMATCH",
+                error: `Current space '${space}' does not match Git remote space '${project.spaceCode}'.`,
+            };
+        const issues = this.context.getGitIssues();
+        if (issues.length)
+            return { success: false, code: "GIT_NOT_READY", error: issues.join(" ") };
+        const input = { ...project };
+        if (this.context.workflowInstanceId) {
+            const id = Number(this.context.workflowInstanceId);
+            if (!Number.isSafeInteger(id))
+                return {
+                    success: false,
+                    code: "INVALID_WORKFLOW_INSTANCE_ID",
+                    error: "WORKFLOW_INSTANCE_ID must be an integer.",
+                };
+            input.workflowInstanceId = id;
+        }
+        try {
+            const run = await this.api.start(input);
+            return {
+                success: true,
+                data: {
+                    ...run,
+                    spaceCode: project.spaceCode,
+                    branchName: project.branchName,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                code: error instanceof CapabilityError
+                    ? error.code
+                    : "PIPELINE_START_FAILED",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}

package/lib/features/space/read/service.js

@@ -0,0 +1,65 @@
+import { failure } from "../../../core/result.js";
+export class SpaceReadService {
+    api;
+    context;
+    constructor(api, context) {
+        this.api = api;
+        this.context = context;
+    }
+    async list() {
+        try {
+            return {
+                success: true,
+                data: {
+                    spaces: await this.api.listSpaces(),
+                    currentSpaceCode: this.context.getSpace(),
+                },
+            };
+        }
+        catch (error) {
+            return failure("Failed to list spaces", error);
+        }
+    }
+    async use(code) {
+        if (this.context.isSpaceFromEnv())
+            return {
+                success: false,
+                code: "SPACE_FROM_ENV",
+                error: `Current space is controlled by ${this.context.spaceEnvKey}. Unset it before switching spaces.`,
+            };
+        try {
+            const spaces = await this.api.listSpaces();
+            const space = spaces.find((item) => item.code === code.trim());
+            if (!space)
+                return {
+                    success: false,
+                    code: "SPACE_NOT_FOUND",
+                    error: `Space is not accessible with the current ${this.context.credentialLabel}: ${code.trim()}`,
+                };
+            this.context.setSpace(space.code);
+            return {
+                success: true,
+                message: `Switched to space: ${space.code}`,
+                data: { space },
+            };
+        }
+        catch (error) {
+            return failure("Failed to switch space", error);
+        }
+    }
+    async get() {
+        const code = this.context.getSpace();
+        if (!code)
+            return {
+                success: false,
+                code: "SPACE_NOT_SELECTED",
+                error: `No current space. Run '${this.context.bin} space use <spaceCode>' first.`,
+            };
+        try {
+            return { success: true, data: { space: await this.api.getSpace(code) } };
+        }
+        catch (error) {
+            return failure(`Failed to get space ${code}`, error);
+        }
+    }
+}

package/lib/lib/command-flags.js

@@ -0,0 +1,12 @@
+import { Flags } from "@oclif/core";
+export const baseFlags = {
+    json: Flags.boolean({
+        description: "Output as JSON",
+        default: false,
+    }),
+    verbose: Flags.boolean({
+        char: "v",
+        description: "Enable verbose output",
+        default: false,
+    }),
+};

package/lib/lib/git-project.js

@@ -0,0 +1,47 @@
+import { execFileSync } from "node:child_process";
+function git(args, cwd = process.cwd()) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+export function parseGitRemote(remoteUrl) {
+    const ssh = remoteUrl.match(/^git@[^:]+:([^/]+)\/([^/]+?)(?:\.git)?$/);
+    const https = remoteUrl.match(/^https?:\/\/[^/]+\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+    const match = ssh ?? https;
+    if (!match)
+        return null;
+    return { tenantCode: match[1], spaceCode: match[2] };
+}
+export function getGitProjectContext(cwd = process.cwd()) {
+    const remote = parseGitRemote(git(["remote", "get-url", "origin"], cwd));
+    const branchName = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    if (!remote || !branchName)
+        return null;
+    return { ...remote, branchName };
+}
+export function getPipelineGitIssues(cwd = process.cwd()) {
+    const issues = [];
+    if (git(["status", "--porcelain"], cwd)) {
+        issues.push("The Git working tree contains uncommitted changes.");
+    }
+    const unpushedText = git(["rev-list", "--count", "@{upstream}..HEAD"], cwd);
+    const unpushedCount = Number.parseInt(unpushedText, 10);
+    if (Number.isFinite(unpushedCount) && unpushedCount > 0) {
+        issues.push(`The current branch contains ${unpushedCount} unpushed commit(s).`);
+    }
+    return issues;
+}
+/** External spaces are selected explicitly; Git organization names are not tenant codes. */
+export function getGitBranch(cwd = process.cwd()) {
+    if (!git(["remote", "get-url", "origin"], cwd))
+        return null;
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    return branch && branch !== "HEAD" ? branch : null;
+}

package/lib/lib/log-paths.js

@@ -0,0 +1,30 @@
+import { runtimeProfile } from "../runtime/profile.js";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { getConfigValue } from "../config/index.js";
+export function getLogDir() {
+    const configured = getConfigValue("log.file.path").trim();
+    const value = configured || `~/${runtimeProfile.configDirName}/logs`;
+    if (value === "~")
+        return homedir();
+    if (value.startsWith("~/"))
+        return join(homedir(), value.slice(2));
+    return isAbsolute(value) ? resolve(value) : resolve(process.cwd(), value);
+}
+export function getLogFilename() {
+    const configured = getConfigValue("log.file.filename").trim();
+    const filename = configured || runtimeProfile.bin;
+    if (basename(filename) !== filename ||
+        !/^[A-Za-z0-9._-]+$/.test(filename) ||
+        filename === "." ||
+        filename === "..") {
+        throw new Error("log.file.filename must contain only letters, numbers, dots, underscores, or hyphens");
+    }
+    return filename;
+}
+export function getTodayLogName(date = new Date()) {
+    return `${getLogFilename()}-${date.toISOString().slice(0, 10)}.log`;
+}
+export function isManagedLogName(name) {
+    return name.startsWith(`${getLogFilename()}-`) && name.endsWith(".log");
+}

package/lib/lib/logger.js

@@ -0,0 +1,146 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, chmodSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import { getConfigValue } from "../config/index.js";
+import { getLogDir, getTodayLogName } from "./log-paths.js";
+export const LogLevel = {
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3,
+};
+const asyncStorage = new AsyncLocalStorage();
+export async function runWithTrace(command, operation) {
+    return asyncStorage.run({ traceId: randomUUID().slice(0, 8), command }, operation);
+}
+export function getTraceId() {
+    return asyncStorage.getStore()?.traceId ?? "no-trace";
+}
+function loadConfig() {
+    try {
+        return {
+            level: normalizeLevel(getConfigValue("log.level"), "INFO"),
+            fileEnabled: getConfigValue("log.file.enabled") !== false,
+            fileLevel: normalizeLevel(getConfigValue("log.file.level"), "DEBUG"),
+        };
+    }
+    catch {
+        return { level: "INFO", fileEnabled: true, fileLevel: "DEBUG" };
+    }
+}
+function normalizeLevel(value, fallback) {
+    const normalized = String(value).toUpperCase();
+    return normalized in LogLevel ? normalized : fallback;
+}
+function shouldLog(level, minimum) {
+    return LogLevel[level] >= LogLevel[minimum];
+}
+function stringifyData(data) {
+    if (data === undefined)
+        return "";
+    if (typeof data === "string")
+        return ` ${data}`;
+    try {
+        return ` ${JSON.stringify(data)}`;
+    }
+    catch {
+        return " [Unserializable data]";
+    }
+}
+function terminalLabel(level) {
+    switch (level) {
+        case "DEBUG":
+            return chalk.gray("debug");
+        case "INFO":
+            return chalk.blue("info");
+        case "WARN":
+            return chalk.yellow.bold("warn");
+        case "ERROR":
+            return chalk.red.bold("error");
+    }
+}
+function writeTerminal(level, message) {
+    process.stderr.write(`${terminalLabel(level)}: ${message}\n`);
+}
+function writeFile(level, message) {
+    try {
+        const logDir = getLogDir();
+        mkdirSync(logDir, { recursive: true, mode: 0o700 });
+        const logFile = join(logDir, getTodayLogName());
+        const context = asyncStorage.getStore();
+        const timestamp = new Date().toISOString();
+        const traceId = context?.traceId ?? "no-trace";
+        const command = context?.command ?? "rkb";
+        appendFileSync(logFile, `[${timestamp}] [${level}] [${traceId}] [${command}] ${message}\n`, { encoding: "utf8", mode: 0o600 });
+        try {
+            chmodSync(logFile, 0o600);
+        }
+        catch {
+            // Some filesystems do not support POSIX permissions.
+        }
+    }
+    catch {
+        // Logging must never make a command fail.
+    }
+}
+function log(level, message, data) {
+    const config = loadConfig();
+    const completeMessage = message + stringifyData(data);
+    if (shouldLog(level, config.level))
+        writeTerminal(level, completeMessage);
+    if (config.fileEnabled && shouldLog(level, config.fileLevel)) {
+        writeFile(level, completeMessage);
+    }
+}
+function terminalOnly(level, message, data) {
+    const config = loadConfig();
+    if (shouldLog(level, config.level)) {
+        writeTerminal(level, message + stringifyData(data));
+    }
+}
+export const logger = {
+    debug(message, data) {
+        log("DEBUG", message, data);
+    },
+    info(message, data) {
+        log("INFO", message, data);
+    },
+    warn(message, data) {
+        log("WARN", message, data);
+    },
+    error(message, data) {
+        log("ERROR", message, data);
+    },
+    success(message, data) {
+        const config = loadConfig();
+        const completeMessage = message + stringifyData(data);
+        if (shouldLog("INFO", config.level)) {
+            process.stderr.write(`${chalk.green.bold("SUCCESS")}: ${completeMessage}\n`);
+        }
+        if (config.fileEnabled && shouldLog("INFO", config.fileLevel)) {
+            writeFile("INFO", `[SUCCESS] ${completeMessage}`);
+        }
+    },
+};
+export const terminalLogger = {
+    debug(message, data) {
+        terminalOnly("DEBUG", message, data);
+    },
+    info(message, data) {
+        terminalOnly("INFO", message, data);
+    },
+    warn(message, data) {
+        terminalOnly("WARN", message, data);
+    },
+    error(message, data) {
+        terminalOnly("ERROR", message, data);
+    },
+    success(message, data) {
+        const config = loadConfig();
+        if (shouldLog("INFO", config.level)) {
+            process.stderr.write(`${chalk.green.bold("SUCCESS")}: ${message + stringifyData(data)}\n`);
+        }
+    },
+};

package/lib/runtime/bootstrap.js

@@ -0,0 +1,7 @@
+import { registerService } from './container.js';
+import { createService as factory0 } from "../adapters/pop/identity.js";
+registerService("identity", factory0);
+import { createService as factory1 } from "../adapters/pop/space-read.js";
+registerService("spaceRead", factory1);
+import { createService as factory2 } from "../adapters/pop/doc-publish.js";
+registerService("docPublish", factory2);

package/lib/runtime/container.js

@@ -0,0 +1,13 @@
+const factories = new Map();
+// Only the build-generated composition root registers concrete implementations.
+export function registerService(key, factory) {
+    if (factories.has(key))
+        throw new Error(`Duplicate service registration: ${key}`);
+    factories.set(key, factory);
+}
+export function getService(key) {
+    const factory = factories.get(key);
+    if (!factory)
+        throw new Error(`Capability is unavailable in this edition: ${key}`);
+    return factory();
+}

package/lib/runtime/profile.js

@@ -0,0 +1,89 @@
+export const runtimeProfile = {
+  "edition": "external",
+  "bin": "rkb",
+  "configDirName": ".rkb-external",
+  "configDirEnv": "RKB_EXTERNAL_CONFIG_DIR",
+  "envPrefix": "RKB_EXTERNAL_ENV_",
+  "spaceKey": "context.spaceCode",
+  "tenantKey": "context.tenantCode",
+  "schema": [
+    {
+      "key": "log.level",
+      "category": "log",
+      "type": "string",
+      "default": "INFO",
+      "description": "Console log level",
+      "enum": [
+        "DEBUG",
+        "INFO",
+        "WARN",
+        "ERROR"
+      ]
+    },
+    {
+      "key": "log.file.enabled",
+      "category": "log",
+      "type": "boolean",
+      "default": true,
+      "description": "Enable file logging"
+    },
+    {
+      "key": "log.file.path",
+      "category": "log",
+      "type": "string",
+      "default": "~/.rkb-external/logs",
+      "description": "Log file directory"
+    },
+    {
+      "key": "log.file.filename",
+      "category": "log",
+      "type": "string",
+      "default": "rkb-external",
+      "description": "Log file name prefix"
+    },
+    {
+      "key": "log.file.level",
+      "category": "log",
+      "type": "string",
+      "default": "DEBUG",
+      "description": "File log level",
+      "enum": [
+        "DEBUG",
+        "INFO",
+        "WARN",
+        "ERROR"
+      ]
+    },
+    {
+      "key": "request.timeout",
+      "category": "request",
+      "type": "number",
+      "default": 30000,
+      "description": "POP request timeout in milliseconds"
+    },
+    {
+      "key": "context.spaceCode",
+      "category": "context",
+      "type": "string",
+      "default": "",
+      "description": "Selected space code"
+    },
+    {
+      "key": "context.tenantCode",
+      "category": "context",
+      "type": "string",
+      "default": "",
+      "description": "Tenant code; empty uses the account tenant"
+    }
+  ],
+  "preview": {
+    "mode": "maas",
+    "cacheWithinConfig": true
+  },
+  "pop": {
+    "endpoint": "raasknowledgebuddy-pre.aliyuncs.com",
+    "apiVersion": "2026-09-02",
+    "requestBodyType": "formData"
+  }
+}
+;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "rkb-cli",
+  "version": "0.3.0-beta.1",
+  "description": "RaaS Knowledge Buddy command-line interface",
+  "type": "module",
+  "bin": {
+    "rkb": "./bin/run.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "edition.json"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@alicloud/openapi-client": "^0.4.15",
+    "@alicloud/tea-util": "^1.4.11",
+    "@oclif/core": "^4.3.0",
+    "chalk": "^4.1.2",
+    "open": "^11.0.0",
+    "yaml": "^2.9.0"
+  },
+  "oclif": {
+    "bin": "rkb",
+    "dirname": "rkb-external",
+    "commands": {
+      "strategy": "explicit",
+      "target": "./lib/command-registry.js"
+    },
+    "topicSeparator": " ",
+    "additionalHelpFlags": [
+      "-h"
+    ],
+    "additionalVersionFlags": [
+      "-V"
+    ]
+  },
+  "private": false
+}