@gaoding/cli 0.0.0 → 1.0.0

package/dist/src/features/tool/use-cases.js

@@ -0,0 +1,177 @@
+import { parseSafeRemoteAssetUrl, UrlSafetyError } from "../../platform/url-safety.js";
+import { findToolModel, projectModelDetail, projectModelList, projectToolList, ToolInputError } from "./catalog.js";
+import { assertModelArguments, buildToolArgumentsSchema } from "./dynamic-schema.js";
+const mediaTypes = {
+    avif: "image/avif",
+    gif: "image/gif",
+    heic: "image/heic",
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    mov: "video/quicktime",
+    mp3: "audio/mpeg",
+    mp4: "video/mp4",
+    png: "image/png",
+    wav: "audio/wav",
+    webm: "video/webm",
+    webp: "image/webp"
+};
+function inferRemoteMediaType(url) {
+    const segment = url.pathname.split("/").filter(Boolean).at(-1) ?? "";
+    let filename = segment;
+    try {
+        filename = decodeURIComponent(segment);
+    }
+    catch {
+        // The extension remains usable when the path contains malformed escapes.
+    }
+    const extension = filename.split(".").at(-1)?.toLowerCase();
+    return extension === undefined || extension === filename.toLowerCase()
+        ? "application/octet-stream"
+        : mediaTypes[extension] ?? "application/octet-stream";
+}
+function remoteMedia(value, name) {
+    try {
+        const url = parseSafeRemoteAssetUrl(value);
+        return {
+            type: "media",
+            url: value,
+            mime: inferRemoteMediaType(url),
+            name
+        };
+    }
+    catch (error) {
+        if (error instanceof UrlSafetyError)
+            throw new ToolInputError();
+        throw error;
+    }
+}
+export function createToolUseCases(dependencies) {
+    async function load(access, signal) {
+        signal.throwIfAborted();
+        const catalog = await dependencies.telemetry.stage("catalog", () => (dependencies.catalog.load({ access, signal })));
+        signal.throwIfAborted();
+        for (const warning of catalog.warnings)
+            dependencies.warn(warning);
+        return catalog;
+    }
+    return {
+        async listTools({ access, signal }) {
+            return projectToolList(await load(access, signal));
+        },
+        async listModels({ input, access, signal }) {
+            return projectModelList(await load(access, signal), input.tool);
+        },
+        async getModel({ input, access, signal }) {
+            return projectModelDetail(await load(access, signal), input.model);
+        },
+        async getArgumentsSchema({ name, access, signal }) {
+            return buildToolArgumentsSchema(await load(access, signal), name);
+        },
+        async call({ input, access, signal }) {
+            const catalog = await load(access, signal);
+            const model = await dependencies.telemetry.stage("input", () => {
+                const modelName = input.arguments.model;
+                if (typeof modelName !== "string")
+                    throw new ToolInputError();
+                const selected = findToolModel(catalog, input.name, modelName);
+                assertModelArguments(selected, input.arguments);
+                return selected;
+            });
+            const { model: ignoredModel, ...parameters } = input.arguments;
+            void ignoredModel;
+            dependencies.telemetry.annotate({
+                tool_name: model.tool,
+                model_id: model.model,
+                parameters
+            });
+            const prompt = [];
+            const requestParameters = {};
+            const directArguments = {};
+            const prepare = async () => {
+                for (const parameter of model.parameters) {
+                    signal.throwIfAborted();
+                    const value = input.arguments[parameter.name];
+                    if (value === undefined)
+                        continue;
+                    if (parameter.type === "string") {
+                        if (parameter.name === "prompt") {
+                            prompt.push({ type: "text", content: value });
+                            directArguments[parameter.name] = value;
+                        }
+                        else {
+                            requestParameters[parameter.name] = value;
+                            directArguments[parameter.name] = value;
+                        }
+                        continue;
+                    }
+                    if (parameter.type === "number") {
+                        requestParameters[parameter.name] = value;
+                        directArguments[parameter.name] = value;
+                        continue;
+                    }
+                    const values = parameter.type === "uri[]" ? value : [value];
+                    for (const mediaUrl of values) {
+                        signal.throwIfAborted();
+                        if (mediaUrl.startsWith("file:")) {
+                            const uploaded = await dependencies.uploader.upload({ url: mediaUrl }, access, signal);
+                            signal.throwIfAborted();
+                            prompt.push({
+                                type: "media",
+                                url: uploaded.url,
+                                mime: uploaded.mediaType,
+                                name: parameter.name
+                            });
+                        }
+                        else {
+                            prompt.push(remoteMedia(mediaUrl, parameter.name));
+                        }
+                    }
+                }
+            };
+            const hasLocalMedia = model.parameters.some((parameter) => {
+                const value = input.arguments[parameter.name];
+                return parameter.type === "uri"
+                    ? typeof value === "string" && value.startsWith("file:")
+                    : parameter.type === "uri[]"
+                        && Array.isArray(value) && value.some((url) => url.startsWith("file:"));
+            });
+            if (hasLocalMedia) {
+                await dependencies.telemetry.stage("upload", prepare);
+            }
+            else {
+                await prepare();
+            }
+            signal.throwIfAborted();
+            const requiresIntent = prompt.some((item) => item.type === "media")
+                || Object.values(requestParameters).some((value) => value === "");
+            const invocation = requiresIntent
+                ? {
+                    kind: "intent",
+                    model: model.model,
+                    prompt,
+                    parameters: requestParameters,
+                    optionalMediaParameters: model.parameters
+                        .filter((parameter) => ((parameter.type === "uri" || parameter.type === "uri[]")
+                        && !parameter.required))
+                        .map((parameter) => parameter.name)
+                }
+                : {
+                    kind: "direct",
+                    name: model.model,
+                    arguments: directArguments
+                };
+            const content = await dependencies.execution.execute({
+                invocation,
+                access,
+                signal
+            });
+            return {
+                content,
+                usage: {
+                    model: model.model,
+                    ...(model.cost === undefined ? {} : { cost: model.cost })
+                }
+            };
+        }
+    };
+}

package/dist/src/features/update/latest-version.js

@@ -0,0 +1,37 @@
+import { valid } from "semver";
+const REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/@gaoding%2fcli";
+export async function fetchLatestVersion(options) {
+    const headers = new Headers({
+        Accept: "application/vnd.npm.install-v1+json"
+    });
+    if (options.etag)
+        headers.set("If-None-Match", options.etag);
+    const response = await options.fetch(REGISTRY_DIST_TAGS_URL, {
+        headers,
+        redirect: "error",
+        signal: options.signal
+    });
+    if (response.status === 304)
+        return { status: "not_modified" };
+    if (!response.ok)
+        throw new Error(`Registry status ${response.status}`);
+    const metadata = await response.json();
+    if (!isRecord(metadata))
+        throw new Error("Registry metadata invalid");
+    const tags = metadata["dist-tags"];
+    if (!isRecord(tags))
+        throw new Error("Registry dist-tags missing");
+    const latest = tags.latest;
+    if (typeof latest !== "string" || valid(latest.trim()) === null) {
+        throw new Error("Registry latest missing");
+    }
+    const etag = response.headers.get("ETag") ?? undefined;
+    return {
+        status: "modified",
+        version: latest.trim(),
+        ...(etag ? { etag } : {})
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/features/update/update-notification.js

@@ -0,0 +1,262 @@
+import { randomUUID } from "node:crypto";
+import * as fileSystem from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { gt, valid } from "semver";
+import { createLocalJsonFile } from "../../platform/local-json-file.js";
+import { fetchLatestVersion } from "./latest-version.js";
+const SUCCESS_CHECK_INTERVAL_MS = 60 * 60 * 1_000;
+const FAILED_CHECK_INTERVAL_MS = 15 * 60 * 1_000;
+const REGISTRY_TIMEOUT_MS = 2_000;
+const STALE_LOCK_MS = 30_000;
+export function createUpdateNotificationService(options) {
+    const fetchPackage = options.fetch ?? globalThis.fetch;
+    const now = options.now ?? (() => new Date());
+    const env = options.env ?? process.env;
+    const stateDirectory = join(options.homeDirectory ?? homedir(), ".gd");
+    const stateFile = options.stateFile ?? createLocalJsonFile({
+        directory: stateDirectory,
+        filename: "update-check.json"
+    });
+    const lock = options.lock ?? createLocalUpdateNotificationLock({
+        directory: stateDirectory,
+        now: () => new Date()
+    });
+    return {
+        async check(signal) {
+            if (env.CI === "true")
+                return;
+            let release = null;
+            try {
+                signal.throwIfAborted();
+                release = await lock.acquire();
+                if (release === null)
+                    return;
+                const checkedAt = now();
+                const today = localDate(checkedAt);
+                const state = await readState(stateFile);
+                if (isNewer(state.latest_version, options.currentVersion)
+                    && state.last_notified_on !== today) {
+                    const reminded = withReminder(state, today, state.latest_version);
+                    await writeState(stateFile, reminded);
+                    notify(options, state.latest_version);
+                    return;
+                }
+                if (!isDue(state.next_check_at, checkedAt))
+                    return;
+                let latestResult;
+                const timeout = signalWithTimeout(signal, REGISTRY_TIMEOUT_MS);
+                try {
+                    latestResult = await fetchLatestVersion({
+                        fetch: fetchPackage,
+                        signal: timeout.signal,
+                        ...(state.etag ? { etag: state.etag } : {})
+                    });
+                }
+                catch {
+                    if (signal.aborted)
+                        return;
+                    await writeState(stateFile, {
+                        ...state,
+                        schema_version: 1,
+                        next_check_at: addMilliseconds(checkedAt, FAILED_CHECK_INTERVAL_MS)
+                    });
+                    return;
+                }
+                finally {
+                    timeout.dispose();
+                }
+                const latest = latestResult.status === "not_modified"
+                    ? state.latest_version
+                    : latestResult.version;
+                if (latest === undefined || valid(latest) === null) {
+                    await writeState(stateFile, {
+                        ...state,
+                        schema_version: 1,
+                        next_check_at: addMilliseconds(checkedAt, FAILED_CHECK_INTERVAL_MS)
+                    });
+                    return;
+                }
+                let nextState = {
+                    ...state,
+                    schema_version: 1,
+                    last_success_check_at: checkedAt.toISOString(),
+                    next_check_at: addMilliseconds(checkedAt, SUCCESS_CHECK_INTERVAL_MS),
+                    latest_version: latest,
+                    ...(latestResult.status === "modified" && latestResult.etag
+                        ? { etag: latestResult.etag }
+                        : {})
+                };
+                if (latestResult.status === "modified" && latestResult.etag === undefined) {
+                    delete nextState.etag;
+                }
+                const shouldNotify = gt(latest, options.currentVersion)
+                    && nextState.last_notified_on !== today;
+                if (shouldNotify)
+                    nextState = withReminder(nextState, today, latest);
+                await writeState(stateFile, nextState);
+                if (shouldNotify)
+                    notify(options, latest);
+            }
+            catch {
+                // Availability checks are best-effort and never change command behavior.
+            }
+            finally {
+                await release?.().catch(() => undefined);
+            }
+        }
+    };
+}
+function signalWithTimeout(parent, milliseconds) {
+    const controller = new AbortController();
+    const forwardAbort = () => { controller.abort(parent.reason); };
+    if (parent.aborted)
+        forwardAbort();
+    else
+        parent.addEventListener("abort", forwardAbort, { once: true });
+    const timer = setTimeout(() => {
+        controller.abort(new Error("Registry request timed out."));
+    }, milliseconds);
+    timer.unref();
+    return {
+        signal: controller.signal,
+        dispose() {
+            clearTimeout(timer);
+            parent.removeEventListener("abort", forwardAbort);
+        }
+    };
+}
+function createLocalUpdateNotificationLock(options) {
+    const path = join(options.directory, "update-check.lock");
+    return {
+        async acquire() {
+            await fileSystem.mkdir(options.directory, { mode: 0o700, recursive: true });
+            await fileSystem.chmod(options.directory, 0o700);
+            const first = await tryCreateLock(path);
+            if (first)
+                return releaseLock(path, first);
+            if (!await isStaleLock(path, options.now()))
+                return null;
+            await fileSystem.unlink(path).catch((error) => {
+                if (!isMissing(error))
+                    throw error;
+            });
+            const recovered = await tryCreateLock(path);
+            return recovered ? releaseLock(path, recovered) : null;
+        }
+    };
+}
+async function tryCreateLock(path) {
+    const token = randomUUID();
+    let handle;
+    try {
+        handle = await fileSystem.open(path, "wx", 0o600);
+        await handle.writeFile(token, "utf8");
+        await handle.sync();
+        await handle.close();
+        return token;
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        if (isExists(error))
+            return null;
+        throw error;
+    }
+}
+function releaseLock(path, token) {
+    return async () => {
+        let current;
+        try {
+            current = await fileSystem.readFile(path, "utf8");
+        }
+        catch (error) {
+            if (isMissing(error))
+                return;
+            throw error;
+        }
+        if (current === token)
+            await fileSystem.unlink(path);
+    };
+}
+async function isStaleLock(path, now) {
+    try {
+        const stats = await fileSystem.stat(path);
+        return stats.mtimeMs + STALE_LOCK_MS <= now.getTime();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return true;
+        throw error;
+    }
+}
+async function readState(file) {
+    const text = await file.readText();
+    if (text === null)
+        return { schema_version: 1 };
+    try {
+        const value = JSON.parse(text);
+        return parseState(value) ?? { schema_version: 1 };
+    }
+    catch {
+        return { schema_version: 1 };
+    }
+}
+function parseState(value) {
+    if (!isRecord(value) || value.schema_version !== 1)
+        return null;
+    for (const key of [
+        "last_success_check_at",
+        "next_check_at",
+        "latest_version",
+        "last_notified_on",
+        "last_notified_version",
+        "etag"
+    ]) {
+        if (value[key] !== undefined && typeof value[key] !== "string")
+            return null;
+    }
+    return value;
+}
+async function writeState(file, state) {
+    await file.writeTextAtomically(`${JSON.stringify(state, null, 2)}\n`);
+}
+function withReminder(state, today, version) {
+    return {
+        ...state,
+        schema_version: 1,
+        last_notified_on: today,
+        last_notified_version: version
+    };
+}
+function notify(options, latest) {
+    options.notify(`gd-cli 有新版本 ${latest}，当前版本为 ${options.currentVersion}。` +
+        "运行 gd-cli update 即可更新。");
+}
+function isNewer(version, currentVersion) {
+    return version !== undefined && valid(version) !== null && gt(version, currentVersion);
+}
+function isDue(nextCheckAt, now) {
+    if (nextCheckAt === undefined)
+        return true;
+    const timestamp = Date.parse(nextCheckAt);
+    return !Number.isFinite(timestamp) || timestamp <= now.getTime();
+}
+function addMilliseconds(value, milliseconds) {
+    return new Date(value.getTime() + milliseconds).toISOString();
+}
+function localDate(value) {
+    return [
+        String(value.getFullYear()).padStart(4, "0"),
+        String(value.getMonth() + 1).padStart(2, "0"),
+        String(value.getDate()).padStart(2, "0")
+    ].join("-");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isExists(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}

package/dist/src/features/update/update-service.js

@@ -0,0 +1,183 @@
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { gt } from "semver";
+import { syncBundledSkills, verifyBundledSkills } from "../skill/installer.js";
+import { fetchLatestVersion } from "./latest-version.js";
+export class UpdateError extends Error {
+    code;
+    nextSteps;
+    constructor(code, message, nextSteps) {
+        super(message);
+        this.code = code;
+        this.nextSteps = nextSteps;
+        this.name = "UpdateError";
+    }
+}
+export function detectInstallSource(input) {
+    const binaryPath = normalizePath(input.binaryPath);
+    const realBinaryPath = normalizePath(input.realBinaryPath);
+    const packageRoot = normalizePath(input.packageRoot);
+    const cwd = normalizePath(resolve(input.cwd));
+    const userAgent = input.env.npm_config_user_agent ?? "";
+    const npmExecPath = normalizePath(input.env.npm_execpath ?? "");
+    if (userAgent.startsWith("yarn/") || npmExecPath.includes("/yarn/")) {
+        return unsupported("Yarn 安装不支持自动更新");
+    }
+    if (containsTemporaryRunner(binaryPath) || containsTemporaryRunner(packageRoot)) {
+        return unsupported("临时运行方式不支持自动更新");
+    }
+    if (binaryPath.includes("/node_modules/.bin/")
+        || packageRoot.startsWith(`${cwd}/node_modules/`)) {
+        return unsupported("项目依赖不支持自动更新");
+    }
+    if (!isWithin(realBinaryPath, packageRoot)) {
+        return unsupported("CLI binary 与 package 不匹配");
+    }
+    if (/\/global\/[^/]+\/\.pnpm\/@gaoding\+cli@[^/]+\/node_modules\/@gaoding\/cli$/u
+        .test(packageRoot)
+        || /\/v\d+\/[0-9a-f]+-[0-9a-f]+-[0-9a-f]{16}\/node_modules\/@gaoding\/cli$/u
+            .test(packageRoot)
+        || /\/v\d+\/[0-9a-f]+-[0-9a-f]+-[0-9a-f]{16}\/node_modules\/@gaoding\/cli\/dist\/bin\/gd-cli\.js$/u
+            .test(binaryPath)) {
+        return { kind: "global", manager: "pnpm", packageRoot: input.packageRoot };
+    }
+    if (packageRoot.endsWith("/lib/node_modules/@gaoding/cli")
+        || packageRoot.endsWith("/npm/node_modules/@gaoding/cli")) {
+        return { kind: "global", manager: "npm", packageRoot: input.packageRoot };
+    }
+    return unsupported("无法确认 npm 或 pnpm 全局安装");
+}
+export function createUpdateService(options) {
+    const fetchPackage = options.fetch ?? globalThis.fetch;
+    const runProcess = options.runProcess ?? spawnProcess;
+    const syncSkills = options.syncSkills ?? syncBundledSkills;
+    const verifySkills = options.verifySkills ?? verifyBundledSkills;
+    const env = options.env ?? process.env;
+    return {
+        async run(signal) {
+            signal.throwIfAborted();
+            const latest = await options.telemetry.stage("registry", async () => {
+                try {
+                    const result = await fetchLatestVersion({ fetch: fetchPackage, signal });
+                    if (result.status !== "modified")
+                        throw new Error("Registry response not modified");
+                    return result.version;
+                }
+                catch (error) {
+                    rethrowAbort(signal);
+                    throw new UpdateError("UPDATE_FAILED", "无法获取 @gaoding/cli 最新版本。", ["请稍后重新执行 gd-cli update。"]);
+                }
+            });
+            signal.throwIfAborted();
+            const skillOptions = {
+                env,
+                ...(options.homeDirectory ? { homeDirectory: options.homeDirectory } : {})
+            };
+            if (!gt(latest, options.currentVersion)) {
+                await options.telemetry.stage("sync", async () => {
+                    try {
+                        await syncSkills(options.bundledSkills, skillOptions);
+                    }
+                    catch (error) {
+                        rethrowAbort(signal);
+                        throw new UpdateError("UPDATE_FAILED", `gd-cli ${options.currentVersion} 无需更新，但 Agent Skill 同步失败。`, ["请解决冲突后重新执行 gd-cli update。"]);
+                    }
+                });
+                return { version: options.currentVersion, updated: false };
+            }
+            const binaryPath = options.binaryPath ?? process.argv[1] ?? "";
+            const source = detectInstallSource({
+                binaryPath,
+                realBinaryPath: safeRealpath(binaryPath),
+                packageRoot: options.packageRoot,
+                cwd: options.cwd ?? process.cwd(),
+                env
+            });
+            const nextSteps = manualCommands(latest);
+            if (source.kind === "unsupported") {
+                throw new UpdateError("UPDATE_FAILED", `当前安装方式不支持自动更新：${source.reason}。`, nextSteps);
+            }
+            const command = source.manager;
+            const args = source.manager === "npm"
+                ? ["install", "--global", "--allow-scripts=@gaoding/cli", `@gaoding/cli@${latest}`]
+                : ["add", "--global", "--allow-build=@gaoding/cli", `@gaoding/cli@${latest}`];
+            await options.telemetry.stage("install", async () => {
+                try {
+                    await runProcess(command, args, signal);
+                }
+                catch (error) {
+                    rethrowAbort(signal);
+                    throw new UpdateError("UPDATE_FAILED", `gd-cli 更新到 ${latest} 失败。`, nextSteps);
+                }
+            });
+            signal.throwIfAborted();
+            const targetSkills = options.bundledSkills.map((skill) => ({
+                ...skill,
+                version: latest
+            }));
+            await options.telemetry.stage("verify", async () => {
+                try {
+                    await verifySkills(targetSkills, skillOptions);
+                }
+                catch (error) {
+                    rethrowAbort(signal);
+                    throw new UpdateError("UPDATE_PARTIAL", `gd-cli 已更新到 ${latest}，但 Agent Skill 验收失败。`, ["请重新执行 gd-cli update。"]);
+                }
+            });
+            return { version: latest, updated: true };
+        }
+    };
+}
+function spawnProcess(command, args, signal) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+            shell: false,
+            signal
+        });
+        child.once("error", reject);
+        child.once("exit", (code, exitSignal) => {
+            if (code === 0) {
+                resolvePromise();
+            }
+            else {
+                reject(new Error(code === null
+                    ? `package manager terminated by ${exitSignal ?? "unknown signal"}`
+                    : `package manager exited with ${code}`));
+            }
+        });
+    });
+}
+function manualCommands(version) {
+    return [
+        `npm install --global --allow-scripts=@gaoding/cli @gaoding/cli@${version}`,
+        `pnpm add --global --allow-build=@gaoding/cli @gaoding/cli@${version}`
+    ];
+}
+function containsTemporaryRunner(path) {
+    return path.includes("/.npm/_npx/")
+        || path.includes("/pnpm/dlx/")
+        || path.includes("/.pnpm/dlx/");
+}
+function isWithin(path, directory) {
+    return path === directory || path.startsWith(`${directory}/`);
+}
+function normalizePath(path) {
+    return path.replace(/\\/gu, "/").replace(/\/+$/u, "");
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function unsupported(reason) {
+    return { kind: "unsupported", reason };
+}
+function rethrowAbort(signal) {
+    if (signal.aborted)
+        signal.throwIfAborted();
+}