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

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.1",
+  "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"