ossput 0.0.1

package/dist/delete-object.d.ts

@@ -0,0 +1,6 @@
+import type { AppConfig, DeleteObjectResult } from "./types.js";
+export interface DeleteObjectOptions {
+    /** 必须为 true，防止 Agent 误删 */
+    confirm: boolean;
+}
+export declare function deleteObject(config: AppConfig, objectKey: string, options: DeleteObjectOptions): Promise<DeleteObjectResult>;

package/dist/delete-object.js

@@ -0,0 +1,26 @@
+import { createOssClient, publicObjectUrl } from "./oss-client.js";
+import { assertDeleteEnabled, assertObjectKeyDeletable, } from "./object-key.js";
+export async function deleteObject(config, objectKey, options) {
+    if (options.confirm !== true) {
+        throw new Error("refusing to delete without confirm: true — show the user objectKey and get explicit approval first");
+    }
+    assertDeleteEnabled(config);
+    const key = assertObjectKeyDeletable(config, objectKey);
+    const client = createOssClient(config);
+    try {
+        await client.head(key);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "NoSuchKey" || e.status === 404) {
+            throw new Error(`object not found: ${key}`);
+        }
+        throw err;
+    }
+    await client.delete(key);
+    return {
+        objectKey: key,
+        deleted: true,
+        objectUrl: publicObjectUrl(config, key),
+    };
+}

package/dist/doctor.d.ts

@@ -0,0 +1,9 @@
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+export declare function runDoctor(profile?: string): Promise<{
+    checks: DoctorCheck[];
+    ok: boolean;
+}>;

package/dist/doctor.js

@@ -0,0 +1,128 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { configExists, findProjectOssputJson, listProfileNames, loadConfigWithProfile, INDEX_CONFIG_PATH, } from "./config-profiles.js";
+import { listConfiguredClients, MCP_CLIENTS } from "./setup/mcp-registry.js";
+import { SKILL_TARGETS, resolveBundledSkillDir } from "./setup/skill-install.js";
+import { testConnectivity } from "./setup/connectivity.js";
+async function pathOk(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkSkillTarget(dest) {
+    if (!(await pathOk(dest))) {
+        return "未安装（运行 ossput skill install）";
+    }
+    try {
+        const st = await lstat(dest);
+        if (st.isSymbolicLink()) {
+            const target = await readlink(dest);
+            const resolved = resolve(dirname(dest), target);
+            const bundled = resolve(resolveBundledSkillDir());
+            if (resolve(resolved) === resolve(bundled)) {
+                return `已链接 → ${resolved}`;
+            }
+            return `符号链接 → ${resolved}`;
+        }
+        return "已复制（非符号链接，升级包后建议重装 Skill）";
+    }
+    catch {
+        return "存在但无法读取";
+    }
+}
+export async function runDoctor(profile) {
+    const checks = [];
+    const nodeMajor = Number(process.version.slice(1).split(".")[0]);
+    checks.push({
+        name: "Node.js",
+        ok: nodeMajor >= 18,
+        detail: nodeMajor >= 18 ? process.version : `${process.version}（需要 ≥18）`,
+    });
+    const hasFetch = typeof globalThis.fetch === "function";
+    checks.push({
+        name: "fetch（上传）",
+        ok: hasFetch,
+        detail: hasFetch
+            ? `Node ${process.version} 内置 fetch`
+            : "不可用（需要 Node.js 18+）",
+    });
+    const configured = await configExists();
+    checks.push({
+        name: "OSS 配置",
+        ok: configured,
+        detail: configured ? INDEX_CONFIG_PATH : `未配置（运行 npx ossput setup）`,
+    });
+    if (configured) {
+        try {
+            const rows = await listProfileNames();
+            const { config, resolved } = await loadConfigWithProfile({ profile });
+            checks.push({
+                name: "当前 Profile",
+                ok: true,
+                detail: `${resolved.name}（${resolved.source}）· ${config.bucket}`,
+            });
+            checks.push({
+                name: "Profile 数量",
+                ok: rows.length > 0,
+                detail: String(rows.length),
+            });
+            try {
+                await testConnectivity(config);
+                checks.push({
+                    name: "Bucket 连通性",
+                    ok: true,
+                    detail: "可访问",
+                });
+            }
+            catch (e) {
+                checks.push({
+                    name: "Bucket 连通性",
+                    ok: false,
+                    detail: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }
+        catch (e) {
+            checks.push({
+                name: "配置加载",
+                ok: false,
+                detail: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    const clients = configured ? await listConfiguredClients() : [];
+    checks.push({
+        name: "MCP 注册",
+        ok: clients.length > 0,
+        detail: clients.length > 0
+            ? clients
+                .map((id) => MCP_CLIENTS.find((c) => c.id === id)?.displayName ?? id)
+                .join(", ")
+            : "未注册（运行 ossput setup）",
+    });
+    for (const target of SKILL_TARGETS) {
+        const dest = target.resolvePath();
+        const detail = await checkSkillTarget(dest);
+        checks.push({
+            name: `Skill · ${target.displayName}`,
+            ok: await pathOk(dest),
+            detail,
+        });
+    }
+    const projectFile = await findProjectOssputJson();
+    if (projectFile) {
+        checks.push({
+            name: "项目绑定",
+            ok: true,
+            detail: projectFile,
+        });
+    }
+    const ok = checks.every((c) => c.ok);
+    return { checks, ok };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+import { startMcpServer } from "./mcp.js";
+const argv = process.argv.slice(2);
+const subcommand = argv[0];
+const MCP_MODE = !subcommand ||
+    subcommand.startsWith("-") ||
+    subcommand === "mcp" ||
+    process.env.OSSPUT_MCP === "1";
+async function main() {
+    if (MCP_MODE && (!subcommand || subcommand === "mcp")) {
+        await startMcpServer();
+        return;
+    }
+    const code = await runCli(argv);
+    process.exit(code);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/key-builder.d.ts

@@ -0,0 +1 @@
+export declare function buildObjectKey(prefix: string, subdir: string, filename: string, overwrite: boolean): string;

package/dist/key-builder.js

@@ -0,0 +1,13 @@
+import { randomUUID } from "node:crypto";
+export function buildObjectKey(prefix, subdir, filename, overwrite) {
+    const ext = filename.includes(".")
+        ? filename.slice(filename.lastIndexOf(".") + 1).toLowerCase()
+        : "bin";
+    const now = new Date();
+    const yyyy = String(now.getUTCFullYear());
+    const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const name = overwrite
+        ? filename.replace(/[^a-zA-Z0-9._-]/g, "_")
+        : `${randomUUID()}.${ext}`;
+    return `${prefix}${subdir}${yyyy}/${mm}/${name}`;
+}

package/dist/list-directories.d.ts

@@ -0,0 +1,11 @@
+import type { AppConfig } from "./types.js";
+export interface ListDirectoriesResult {
+    prefix: string;
+    count: number;
+    directories: string[];
+}
+/** 递归列出 prefix 下所有「目录」（CommonPrefixes） */
+export declare function listDirectories(config: AppConfig, options?: {
+    subdir?: string;
+}): Promise<ListDirectoriesResult>;
+export declare function formatDirectoriesAsMarkdown(result: ListDirectoriesResult): string;

package/dist/list-directories.js

@@ -0,0 +1,64 @@
+import { formatPrefixDisplay, normalizePrefix } from "./config.js";
+import { createOssClient } from "./oss-client.js";
+import { validateSubdir } from "./validators.js";
+function buildListPrefix(config, subdir) {
+    const sub = validateSubdir(subdir);
+    if (!sub)
+        return config.prefix;
+    const normalized = sub.endsWith("/") ? sub : `${sub}/`;
+    return `${config.prefix}${normalized}`;
+}
+async function listImmediateSubdirs(client, prefix) {
+    const dirs = [];
+    let marker;
+    do {
+        const page = await client.list({ prefix, delimiter: "/", marker, "max-keys": 1000 }, {});
+        for (const p of page.prefixes ?? [])
+            dirs.push(p);
+        marker = page.isTruncated ? page.nextMarker : undefined;
+    } while (marker);
+    return dirs;
+}
+/** 递归列出 prefix 下所有「目录」（CommonPrefixes） */
+export async function listDirectories(config, options) {
+    const prefix = buildListPrefix(config, options?.subdir);
+    const client = createOssClient(config);
+    const all = [];
+    async function walk(current) {
+        const children = await listImmediateSubdirs(client, current);
+        for (const dir of children.sort()) {
+            all.push(dir);
+            await walk(dir);
+        }
+    }
+    await walk(prefix);
+    return {
+        prefix: formatPrefixDisplay(prefix),
+        count: all.length,
+        directories: all,
+    };
+}
+export function formatDirectoriesAsMarkdown(result) {
+    const lines = [
+        `# OSS 目录列表`,
+        ``,
+        `- **前缀**: \`${result.prefix}\``,
+        `- **目录数**: ${result.count}`,
+        ``,
+    ];
+    if (result.count === 0) {
+        lines.push(`_（无子目录）_`);
+        return lines.join("\n");
+    }
+    const rootNorm = result.prefix === "/" ? "" : normalizePrefix(result.prefix);
+    lines.push("```");
+    for (const dir of result.directories) {
+        const rel = rootNorm && dir.startsWith(rootNorm) ? dir.slice(rootNorm.length) : dir;
+        const depth = rel.replace(/\/$/, "").split("/").filter(Boolean).length - 1;
+        const indent = "  ".repeat(Math.max(0, depth));
+        const label = rel.replace(/\/$/, "").split("/").filter(Boolean).pop() ?? dir;
+        lines.push(`${indent}${label}/`);
+    }
+    lines.push("```");
+    return lines.join("\n");
+}

package/dist/list-format.d.ts

@@ -0,0 +1,6 @@
+import type { ListObjectsResult, OssObjectInfo } from "./types.js";
+export declare function isPreviewableImage(objectKey: string): boolean;
+export declare function filterObjects(objects: OssObjectInfo[], imagesOnly: boolean): OssObjectInfo[];
+export declare function formatListAsMarkdown(result: ListObjectsResult, options?: {
+    previewMax?: number;
+}): string;

package/dist/list-format.js

@@ -0,0 +1,57 @@
+import { formatPrefixDisplay } from "./config.js";
+const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg"]);
+export function isPreviewableImage(objectKey) {
+    const dot = objectKey.lastIndexOf(".");
+    if (dot < 0)
+        return false;
+    return IMAGE_EXT.has(objectKey.slice(dot + 1).toLowerCase());
+}
+function formatBytes(size) {
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${(size / 1024).toFixed(1)} KB`;
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+function basename(objectKey) {
+    const slash = objectKey.lastIndexOf("/");
+    return slash >= 0 ? objectKey.slice(slash + 1) : objectKey;
+}
+export function filterObjects(objects, imagesOnly) {
+    if (!imagesOnly)
+        return objects;
+    return objects.filter((o) => isPreviewableImage(o.objectKey));
+}
+export function formatListAsMarkdown(result, options) {
+    const previewMax = Math.min(options?.previewMax ?? 20, 50);
+    const lines = [
+        `# OSS 文件列表`,
+        ``,
+        `- **前缀**: \`${formatPrefixDisplay(result.prefix)}\``,
+        `- **数量**: ${result.count}${result.truncated ? "（已截断，可增大 maxKeys 或缩小 subdir）" : ""}`,
+        ``,
+    ];
+    const images = result.objects.filter((o) => isPreviewableImage(o.objectKey));
+    const others = result.objects.filter((o) => !isPreviewableImage(o.objectKey));
+    if (images.length > 0) {
+        lines.push(`## 图片预览`, ``);
+        for (const obj of images.slice(0, previewMax)) {
+            const name = basename(obj.objectKey);
+            lines.push(`### ${name}`, ``, `![${name}](${obj.objectUrl})`, ``, `- **地址**: ${obj.objectUrl}`, `- **Key**: \`${obj.objectKey}\``, `- **大小**: ${formatBytes(obj.size)}`, `- **更新**: ${obj.lastModified}`, ``);
+        }
+        if (images.length > previewMax) {
+            lines.push(`_… 另有 ${images.length - previewMax} 张图片未展示预览_`, ``);
+        }
+    }
+    const listOthers = images.length > 0 ? others : result.objects;
+    if (listOthers.length > 0) {
+        lines.push(`## 文件地址`, ``);
+        lines.push(`| 文件 | 大小 | 地址 |`, `| --- | --- | --- |`);
+        for (const obj of listOthers) {
+            const name = basename(obj.objectKey);
+            lines.push(`| ${name} | ${formatBytes(obj.size)} | ${obj.objectUrl} |`);
+        }
+        lines.push(``);
+    }
+    return lines.join("\n");
+}

package/dist/list-objects.d.ts

@@ -0,0 +1,7 @@
+import type { AppConfig, ListObjectsResult } from "./types.js";
+export interface ListObjectsOptions {
+    subdir?: string;
+    maxKeys?: number;
+    imagesOnly?: boolean;
+}
+export declare function listObjects(config: AppConfig, options?: ListObjectsOptions): Promise<ListObjectsResult>;

package/dist/list-objects.js

@@ -0,0 +1,47 @@
+import { formatPrefixDisplay } from "./config.js";
+import { filterObjects } from "./list-format.js";
+import { createOssClient, publicObjectUrl } from "./oss-client.js";
+import { validateSubdir } from "./validators.js";
+function buildListPrefix(config, subdir) {
+    const sub = validateSubdir(subdir);
+    if (!sub)
+        return config.prefix;
+    const normalized = sub.endsWith("/") ? sub : `${sub}/`;
+    return `${config.prefix}${normalized}`;
+}
+export async function listObjects(config, options) {
+    const prefix = buildListPrefix(config, options?.subdir);
+    const limit = Math.min(Math.max(options?.maxKeys ?? 1000, 1), 1000);
+    const client = createOssClient(config);
+    const objects = [];
+    let marker;
+    let truncated = false;
+    do {
+        const page = await client.list({
+            prefix,
+            marker,
+            "max-keys": Math.min(limit - objects.length, 1000),
+        }, {});
+        for (const obj of page.objects ?? []) {
+            if (obj.name.endsWith("/"))
+                continue;
+            objects.push({
+                objectKey: obj.name,
+                size: Number(obj.size ?? 0),
+                lastModified: String(obj.lastModified ?? ""),
+                objectUrl: publicObjectUrl(config, obj.name),
+            });
+            if (objects.length >= limit)
+                break;
+        }
+        truncated = Boolean(page.isTruncated) || objects.length >= limit;
+        marker = page.isTruncated ? page.nextMarker : undefined;
+    } while (marker && objects.length < limit);
+    const filtered = filterObjects(objects, Boolean(options?.imagesOnly));
+    return {
+        prefix: formatPrefixDisplay(prefix),
+        count: filtered.length,
+        objects: filtered,
+        truncated,
+    };
+}

package/dist/mcp-annotations.d.ts

@@ -0,0 +1,16 @@
+/** MCP tool annotation hints for clients (non-authoritative). */
+export declare const MCP_READ_ONLY: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: true;
+};
+export declare const MCP_WRITE: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: false;
+    readonly openWorldHint: true;
+};
+export declare const MCP_DESTRUCTIVE: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: true;
+};

package/dist/mcp-annotations.js

@@ -0,0 +1,16 @@
+/** MCP tool annotation hints for clients (non-authoritative). */
+export const MCP_READ_ONLY = {
+    readOnlyHint: true,
+    openWorldHint: true,
+};
+export const MCP_WRITE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+};
+export const MCP_DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};

package/dist/mcp-result.d.ts

@@ -0,0 +1,14 @@
+type TextContent = {
+    type: "text";
+    text: string;
+};
+export type McpToolResult = {
+    content: TextContent[];
+    isError?: boolean;
+};
+export declare function mcpJson(data: unknown): McpToolResult;
+export declare function mcpText(text: string): McpToolResult;
+export declare function mcpError(message: string, nextStep?: string): McpToolResult;
+export declare function mcpErrorFromUnknown(err: unknown): McpToolResult;
+export declare function runMcpTool<T extends McpToolResult>(fn: () => Promise<T>): Promise<McpToolResult>;
+export {};

package/dist/mcp-result.js

@@ -0,0 +1,57 @@
+export function mcpJson(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function mcpText(text) {
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+export function mcpError(message, nextStep) {
+    const lines = [message];
+    if (nextStep) {
+        lines.push("", `下一步：${nextStep}`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        isError: true,
+    };
+}
+export function mcpErrorFromUnknown(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    let nextStep;
+    if (/not configured|未配置/i.test(message)) {
+        nextStep = "在终端运行 npx ossput setup，然后重启 IDE";
+    }
+    else if (/allowDelete|confirm: true|refusing to delete/i.test(message)) {
+        nextStep =
+            "删除需在 profile 设 allowDelete:true，并向用户确认后再传 confirm:true 与完整 objectKey";
+    }
+    else if (/upload failed|OSS upload/i.test(message)) {
+        nextStep = "检查网络、RAM 权限与 presigned URL 是否过期";
+    }
+    else if (/fetch|Node\.js 18/i.test(message)) {
+        nextStep = "使用 Node.js 18 或更高版本";
+    }
+    else if (/extension|subdir|refusing/i.test(message)) {
+        nextStep = "检查文件类型、subdir 命名或是否误选敏感文件";
+    }
+    else if (/AccessDenied|InvalidAccessKeyId|SignatureDoesNotMatch/i.test(message)) {
+        nextStep = "检查 RAM 权限与 AccessKey，或运行 ossput doctor";
+    }
+    return mcpError(message, nextStep);
+}
+export async function runMcpTool(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        return mcpErrorFromUnknown(err);
+    }
+}

package/dist/mcp.d.ts

@@ -0,0 +1,4 @@
+import { inferContentType } from "./validators.js";
+export declare function startMcpServer(): Promise<void>;
+export declare function getSetupStatusJson(profile?: string): Promise<Record<string, unknown>>;
+export { inferContentType };