@coralai/sps-plugin-storage-sync 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export declare const name = "storage-sync";
 export declare const category = "\u5B58\u50A8";
 export declare const description = "\u5DE5\u4F5C\u533A \u2192 \u5BF9\u8C61\u5B58\u50A8\u540C\u6B65:\u6309\u4EA7\u54C1\u58F0\u660E\u7684\u8303\u56F4,\u628A\u7528\u6237\u4EA7\u7269\u589E\u91CF\u642C\u5230 S3 \u517C\u5BB9\u6876\u3002";
 interface ApplyCtx {
-    effect(fn: () => void): void;
+    effect(fn: () => (() => void) | void): void;
     logger?: {
         info(msg: string): void;
         warn(msg: string): void;

package/dist/index.js

@@ -65,13 +65,19 @@ export function apply(ctx, config) {
     //    没查线上装着的插件 ⇒ gameforge-art 永远 PENDING、六个 art.* 能力全缺席。
     //    ⇒ 契约留在 `@coralai/sps-plugin-api`,**实现跟着持有桶凭据的这个插件走**。
     const backend = new MinioBackend(config);
-    const disposeStorage = ctx.reflect.provide('sps.storage', {
+    // 🔴 `ctx.effect(fn)` **立即执行 fn**,并把 fn 的返回值当卸载时的 disposer。
+    //    第一版写成 `const d = provide(...); ctx.effect(() => d())` ——
+    //    那当场就把刚 provide 的服务撤销了,而且**没有任何报错**:
+    //    apply 照常跑完、日志照常打,只有 inject 它的插件永远 PENDING。
+    //    (2026-08-28 实测:线上 `reflect.get('sps.storage')` 拿不到,
+    //     而同一次装配里 `[sps-sync] 常驻` 已经打出来了。)
+    //    ⇒ 本仓先例是 `ctx.effect(() => ctx[AGENTS].register(f))` —— register 返回 unregister。
+    ctx.effect(() => ctx.reflect.provide('sps.storage', {
         configured: () => Boolean(config.endpoint && config.bucket && config.enabled !== false),
         get: (key) => backend.get(key),
         list: (prefix) => backend.list(prefix),
         put: (key, bytes, contentType) => backend.put(key, bytes, contentType),
-    });
-    ctx.effect(() => disposeStorage());
+    }));
     log(`[sps-sync] 常驻:间隔=${intervalMs}ms 范围=近 ${sinceDays || '∞'} 天`);
     void tick().finally(schedule);
     // 插件卸载/重挂时停掉循环 —— 否则改一次配置就多一个循环在跑。

package/dist/syncable.d.ts

@@ -1,26 +1,41 @@
-export type SyncRejection = {
-    code: 'ABSOLUTE';
-    rel: string;
-} | {
-    code: 'DOT_SEGMENT';
-    rel: string;
-} | {
-    code: 'PARENT_SEGMENT';
-    rel: string;
-} | {
-    code: 'EMPTY_SEGMENT';
-    rel: string;
-} | {
-    code: 'ESCAPES_PROJECT';
-    rel: string;
-};
 /**
- * 纯字符串这一半(**不含**软链检查 —— 那半必须走 `isRealUnderRoot`)。
+ * @module        providers/storage/syncable
+ * @description   **同步**这条路的安全下限。设计见 `object-storage-and-workspace-sync.md` §2.1 第五条。
+ *
+ * @layer         providers
+ *
+ * 🔴🔴 **它与发布的下限方向相反,别互相抄。**
+ * ```
+ * 发布 publishable()  怕**多发** —— 树里会长出什么由 agent 决定,黑名单追不上 ⇒ **后缀白名单**
+ * 同步 syncable()     怕**少发** —— 用户会放 .blend / .psd / .aseprite ⇒ **不能用后缀白名单**
+ * ```
+ * 抄错方向的表现是:**用户的源文件不见了,而且不报错**。
+ * (「照搬一份现成的安全规则」恰恰是最容易顺手抄整份的时候。)
+ *
+ * 🔴 **声明决定"要什么",本模块决定"绝不给什么"** —— 后者不是产品知识,是主体安全,
+ * 且**不可被声明或配置放宽**。它防的是一件具体的事:项目树里有带活 token 的
+ * `.claude/settings.local.json`(实测:coral 那侧 `publishable('src/main.js')` 放行,
+ * 而 `readFile` 实际拿到 `ANTHROPIC_AUTH_TOKEN=sk-live-…`,落点还是公开可取的前缀)。
+ *
+ * 🔴 **真正拦住凭据的是"任一路径段以 `.` 开头"这一条**,不是别的:
+ * `settings.local.json` 本身后缀无害,是 `.claude/` 这个点开头段拦住的。
+ * ⇒ 将来谁"为了支持 `.well-known/` 放宽点开头",会在不知情的情况下把底线整个打开。
+ * > 判据:**守卫要标注它靠哪一条在生效** —— 否则放宽的人以为自己在动一条无关的规则。
+ */
+import { type SyncRejection as ShapeRejection, syncableShape } from '@coralai/sps-plugin-api';
+export { syncableShape };
+/**
+ * 完整的拒绝理由 = **形状**(契约包那 4 个)+ **围栏**(这一个)。
  *
- * 单独抽出来不是为了复用,是为了让**两半都必须被调用**这件事在类型上看得见:
- * 只调这一半的实现会"看起来对",而它恰恰漏掉了唯一挡得住 agent 自造软链的那道。
+ * ⚠️ 两者不该合并进契约包:形状是纯字符串判断,任何地方都能算;
+ *    `ESCAPES_PROJECT` 要 realpath、要项目根,是**运行时**的结果。
+ *    合进去会让"只调形状那一半"看起来像完整判据 —— 而那正是漏掉软链的写法。
  */
-export declare function syncableShape(rel: string): SyncRejection | null;
+export type SyncRejection = ShapeRejection | {
+    code: 'ESCAPES_PROJECT';
+    rel: string;
+};
+export type SyncRejectCode = SyncRejection['code'];
 /**
  * 完整判据 = 形状 + **realpath 围栏**。
  *

package/dist/syncable.js

@@ -22,29 +22,11 @@
  * ⇒ 将来谁"为了支持 `.well-known/` 放宽点开头",会在不知情的情况下把底线整个打开。
  * > 判据:**守卫要标注它靠哪一条在生效** —— 否则放宽的人以为自己在动一条无关的规则。
  */
-import { isRealUnderRoot } from '@coralai/sps-plugin-api';
-/**
- * 纯字符串这一半(**不含**软链检查 —— 那半必须走 `isRealUnderRoot`)。
- *
- * 单独抽出来不是为了复用,是为了让**两半都必须被调用**这件事在类型上看得见:
- * 只调这一半的实现会"看起来对",而它恰恰漏掉了唯一挡得住 agent 自造软链的那道。
- */
-export function syncableShape(rel) {
-    if (!rel)
-        return { code: 'EMPTY_SEGMENT', rel };
-    if (rel.startsWith('/'))
-        return { code: 'ABSOLUTE', rel };
-    for (const seg of rel.split('/')) {
-        if (!seg)
-            return { code: 'EMPTY_SEGMENT', rel };
-        if (seg === '..')
-            return { code: 'PARENT_SEGMENT', rel };
-        // ← 承重的是这条:`.claude/`、`.git/`、`.sps/` 全靠它
-        if (seg.startsWith('.'))
-            return { code: 'DOT_SEGMENT', rel };
-    }
-    return null;
-}
+import { isRealUnderRoot, syncableShape, } from '@coralai/sps-plugin-api';
+// 🔴 形状判据的真源在 `@coralai/sps-plugin-api` —— **两个地方要用同一份**:
+//    这里(同步时判每个文件)与宿主(写 sync-scope 声明时判每条 include)。
+//    各写一份的话,写入口放行的声明会在同步时被静默挡掉,而配置的人看不到。
+export { syncableShape };
 /**
  * 完整判据 = 形状 + **realpath 围栏**。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralai/sps-plugin-storage-sync",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "工作区 → 对象存储同步:把节点本地盘上的用户产物搬到共享面(S3 兼容桶)。",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@coralai/sps-plugin-api": "^0.14.0"
+    "@coralai/sps-plugin-api": "^0.16.0"
   },
   "optionalDependencies": {
     "minio": "^8.0.7"