@coralai/sps-plugin-api 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -382,7 +382,37 @@ export interface SpsWorkspace {
     discover(): Promise<SpsWorkspaceProject[]>;
     /** 某产品的用户资产范围。没有声明时回落窄兜底,并把 `usedDefault` 置真。 */
     assetScope(product: string): SpsAssetScope;
+    /**
+     * 构建方声明的产物目录(`<repoDir>/.sps/build.json` 的 `outDir`)。
+     *
+     * 🔴 **三态,别塌成两态**:
+     * ```
+     * undefined  没声明（文件不在 / 没这个字段 / 坏 JSON）
+     * null       声明了「这个项目没有产物目录」
+     * string     声明的相对目录
+     * ```
+     *    把 `null` 和 `undefined` 合成一个,就分不出「构建方说没有」和「构建方没说」——
+     *    而前者该照做,后者只能去猜。
+     *
+     * 🔴 **别自己读 `.sps/build.json`。** 它取代的正是"三方各自猜"那个形状:
+     *    sps 的 play.ts、插件的 publish.mjs 曾各写一份
+     *    `exists(dist/index.html) ? dist : repoDir` 的三元(逐字相同)。
+     *    现有项目全是 vite(默认 `dist`)所以一直没露;webpack 默认 `build`、Next 是 `.next`
+     *    ⇒ 只要有一个项目的打包器输出不是 dist,猜的那份当场就错,而表现是
+     *    "预览到未构建的源码",**零报错**。
+     *
+     * ⚠️ 它在 `sps.workspace` 而不是别处,是因为这是**读工作区里的一个约定文件** ——
+     *    和 `assetScope` 同类:约定由宿主定,插件问宿主要答案,而不是自己拼路径。
+     */
+    declaredOutDir(repoDir: string): string | null | undefined;
+}
+export type SyncRejectCode = 'EMPTY_SEGMENT' | 'ABSOLUTE' | 'PARENT_SEGMENT' | 'DOT_SEGMENT';
+export interface SyncRejection {
+    code: SyncRejectCode;
+    rel: string;
 }
+/** 相对路径的形状判据。返回 `null` = 形状没问题(**不代表可同步**,还要过软链围栏)。 */
+export declare function syncableShape(rel: string): SyncRejection | null;
 /**
  * `p` 是否在 `root` 之内(含 root 自身)。
  *

package/dist/index.js

@@ -13,6 +13,23 @@
  */
 import { realpath } from 'node:fs/promises';
 import { dirname, join, resolve as nodeResolve, sep } from 'node:path';
+/** 相对路径的形状判据。返回 `null` = 形状没问题(**不代表可同步**,还要过软链围栏)。 */
+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;
+}
 // ── 路径围栏:所有插件共用的安全下限 ──────────────────────────────────────
 //
 // 🔴 **安全判据不能有第二份。** 本仓已经为这个形状付过三次代价:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralai/sps-plugin-api",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "sps 宿主半区的插件契约:ctx 上那些服务的方法签名。插件装它拿类型。",
   "type": "module",
   "main": "./dist/index.js",