@sema-agent/settings-schema 11.2.0 → 12.0.0

package/dist/web-admin-credential.js

@@ -22,16 +22,11 @@
 import { z } from "zod";
 import { looksLikeJwt } from "./api/auth-bridge.js";
 import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
+import { buildQuotedIssue } from "./quoted-issue.js";
+import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (a project registration's `archivedAt` reads the same one)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
 export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
-/** RFC 3339 `date-time` 的**剖面**:zod 的 `z.iso.datetime({offset:true})` 管日历有效性(月日范围、闰年、时分秒范围),
- *  这里的正则自己判另三处 —— 秒必备、数字偏移必须是 `±hh:mm`、偏移的时 00–23 / 分 00–59(`10:00Z`、`+0800` 与 `+99:99`
- *  都不是 RFC 3339,后者 `Date.parse` 读成 NaN)。这三处的判据在本正则,不随 zod 哪一版收不收而变。大写 `T` / `Z`、不收闰秒 `:60`:读方普遍用
- *  `Date.parse` 取时刻,这是那组形里它处处读得准的子集。 */
-const RFC3339_DATE_TIME = z.iso
-    .datetime({ offset: true })
-    .regex(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/, "must be an RFC 3339 date-time: seconds and a Z / ±hh:mm offset (hh 00-23, mm 00-59) are required");
 /** 一枚**令牌串**的形 —— 裸行 bearer、信封里的 `accessToken` / `refreshToken` 共用这**一条**律:可打印 ASCII
  *  (0x20–0x7E),首尾是可见字符(0x21–0x7E)、中间可有空格(共享令牌可以是一句口令 —— 验修轮 N2:今天走得通的
  *  这种令牌不许被本律拒掉)。控制字符、制表、非 ASCII、不可见字符一律不是令牌:判别器把它判 `unreadable`,而不是
@@ -50,13 +45,13 @@ const TokenString = z.string().regex(TOKEN_CHARS, "must be a token: printable AS
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
- *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ *    同不同源由读方比。URL 形判据是包内 URL 判官的「非存量座位」那一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据;issuer 是 wire 输入、不是存量,一次性迁移不碰它,fragment 拒句因此不指路)—— 本包不另写一份更窄的 URL 律。
  */
 export const WebAdminCredentialEnvelope = z
     .object({
     kind: z.literal(WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND),
-    accessToken: TokenString.refine(looksLikeJwt, "must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope"),
+    accessToken: TokenString.refine(looksLikeJwt, buildQuotedIssue `must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope`),
     refreshToken: TokenString,
     expiresAt: RFC3339_DATE_TIME,
     issuer: NON_SECRET_URL_NO_MIGRATION,

package/dist/write-failure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):原子写器(`./atomic-write`)写失败的**唯一一句** —— 按失败落在哪一步、errno 是什么分句,
+ * 句尾给那一步对应的出路。写器有两步:在目标所在目录里建临时文件(`create`,连同恢复沿用的模式)、`rename` 盖过目标(`replace`)。
+ * 改前一句话包打天下(「cannot write <文件>: <Node 的错误句> … fix the cause」):目录不可写时点名的却是文件(Node 句子里是临时文件的路径),
+ * 而可写目录里的只读文件照常写得进 —— 句子把人指向了错的那一个。命令行(`./cli`)认这只错误类型、原样印它的句子。
+ */
+/** 原子写的两步(闭集)。 */
+export type AtomicWriteStep = "create" | "replace";
+/** 一次写失败的句子(纯函数)。认得的 errno 给对应出路;别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。 */
+export declare function atomicWriteFailureSentence(step: AtomicWriteStep, dir: string, file: string, cause: unknown): string;
+/** 原子写器抛的错:句子见 {@link atomicWriteFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
+export declare class AtomicWriteFailure extends Error {
+    readonly step: AtomicWriteStep;
+    readonly code: string | undefined;
+    constructor(step: AtomicWriteStep, dir: string, file: string, cause: unknown);
+}

package/dist/write-failure.js

@@ -0,0 +1,43 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):原子写器(`./atomic-write`)写失败的**唯一一句** —— 按失败落在哪一步、errno 是什么分句,
+ * 句尾给那一步对应的出路。写器有两步:在目标所在目录里建临时文件(`create`,连同恢复沿用的模式)、`rename` 盖过目标(`replace`)。
+ * 改前一句话包打天下(「cannot write <文件>: <Node 的错误句> … fix the cause」):目录不可写时点名的却是文件(Node 句子里是临时文件的路径),
+ * 而可写目录里的只读文件照常写得进 —— 句子把人指向了错的那一个。命令行(`./cli`)认这只错误类型、原样印它的句子。
+ */
+/** `create` 步里「目录本身不让建文件」的 errno:权限不够、只读文件系统、目录不在。出路 = 让目录可写。 */
+const DIRECTORY_NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT"]);
+/** `replace` 步里「目录收新文件、却换不掉这一份」的 errno:不可变标志、粘滞目录里别人的文件。出路 = 让文件可被替换。 */
+const FILE_NOT_REPLACEABLE = new Set(["EACCES", "EPERM"]);
+const errnoOf = (e) => {
+    const code = e?.code;
+    return typeof code === "string" ? code : undefined;
+};
+const messageOf = (e) => (e instanceof Error ? e.message : String(e)).replace(/\s*\n\s*/g, " ");
+/** 一次写失败的句子(纯函数)。认得的 errno 给对应出路;别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。 */
+export function atomicWriteFailureSentence(step, dir, file, cause) {
+    const code = errnoOf(cause);
+    const tag = code === undefined ? "" : ` (${code})`;
+    switch (step) {
+        case "create":
+            return code !== undefined && DIRECTORY_NOT_WRITABLE.has(code) ? `cannot write into directory ${dir}${tag}: make the directory writable` : `cannot write into directory ${dir}${tag}: ${messageOf(cause)}`;
+        case "replace":
+            return code !== undefined && FILE_NOT_REPLACEABLE.has(code)
+                ? `cannot replace ${file}${tag}: make the file replaceable — clear an immutable flag; in a sticky directory only the file's owner may replace it`
+                : `cannot replace ${file}${tag}: ${messageOf(cause)}`;
+        default: {
+            const unhandled = step;
+            throw new Error(`atomicWriteFailureSentence: unhandled step ${String(unhandled)}`);
+        }
+    }
+}
+/** 原子写器抛的错:句子见 {@link atomicWriteFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
+export class AtomicWriteFailure extends Error {
+    step;
+    code;
+    constructor(step, dir, file, cause) {
+        super(atomicWriteFailureSentence(step, dir, file, cause), { cause });
+        this.name = "AtomicWriteFailure";
+        this.step = step;
+        this.code = errnoOf(cause);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",