@coralai/sps-cli 0.49.16 → 0.50.0

package/dist/shared/errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module        shared/errors
+ * @description   DomainError —— 所有 Service 层错误的统一结构
+ *
+ * @layer         shared
+ *
+ * Delivery 层（CLI / HTTP）负责翻译 DomainError 到各自输出格式：
+ *   - HTTP：toHttpStatus + problem+json body
+ *   - CLI：toExitCode + stderr 渲染
+ *
+ * Domain 层允许正常抛 Error；Service 层捕获后转 DomainError。
+ */
+export type DomainErrorKind = 
+/** 资源不存在 —— HTTP 404 / CLI exit 1 */
+'not-found'
+/** etag 冲突 / 状态冲突 / 并发竞争 —— HTTP 409 / CLI exit 1 */
+ | 'conflict'
+/** 入参非法（格式、schema 违反）—— HTTP 422 / CLI exit 2 */
+ | 'validation'
+/** 前置条件不满足（业务规则阻挡）—— HTTP 409 / CLI exit 2 */
+ | 'precondition'
+/** 外部系统错误（Git 失败 / npm registry 不通）—— HTTP 502 / CLI exit 3 */
+ | 'external'
+/** 未知内部错误 —— HTTP 500 / CLI exit 1 */
+ | 'internal';
+export interface DomainError {
+    readonly kind: DomainErrorKind;
+    /** 机读码（全大写 + 下划线），便于 i18n / 客户端分支。 */
+    readonly code: string;
+    /** 人读消息（默认中文），展示给终端用户。 */
+    readonly message: string;
+    /** 结构化上下文 —— 不含大对象 / 不含敏感数据。 */
+    readonly details?: Readonly<Record<string, unknown>>;
+    /** 原始异常 —— 仅日志 / debug 用，不暴露给客户端。 */
+    readonly cause?: unknown;
+}
+/** 构造 DomainError 的 factory（避免到处写 `{ kind, code, message }` 字面量）。 */
+export declare function domainError(kind: DomainErrorKind, code: string, message: string, extra?: {
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}): DomainError;
+/** HTTP status code 映射 —— Console route 层用。 */
+export declare function toHttpStatus(e: DomainError): number;
+/** CLI exit code 映射 —— CLI command 层用。 */
+export declare function toExitCode(e: DomainError): number;
+/**
+ * 翻译为 application/problem+json（RFC 7807 兼容 shape）。
+ * Delivery 层的 HTTP 响应体用。
+ */
+export interface ProblemJson {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    code: string;
+    [k: string]: unknown;
+}
+export declare function toProblemJson(e: DomainError): ProblemJson;
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,eAAe;AACzB,qCAAqC;AACnC,WAAW;AACb,qDAAqD;GACnD,UAAU;AACZ,iDAAiD;GAC/C,YAAY;AACd,8CAA8C;GAC5C,cAAc;AAChB,+DAA+D;GAC7D,UAAU;AACZ,sCAAsC;GACpC,UAAU,CAAC;AAEf,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CACzB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GACjE,WAAW,CAQb;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAcnD;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAYjD;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CASzD"}

package/dist/shared/errors.js

@@ -0,0 +1,79 @@
+/**
+ * @module        shared/errors
+ * @description   DomainError —— 所有 Service 层错误的统一结构
+ *
+ * @layer         shared
+ *
+ * Delivery 层（CLI / HTTP）负责翻译 DomainError 到各自输出格式：
+ *   - HTTP：toHttpStatus + problem+json body
+ *   - CLI：toExitCode + stderr 渲染
+ *
+ * Domain 层允许正常抛 Error；Service 层捕获后转 DomainError。
+ */
+/** 构造 DomainError 的 factory（避免到处写 `{ kind, code, message }` 字面量）。 */
+export function domainError(kind, code, message, extra = {}) {
+    return {
+        kind,
+        code,
+        message,
+        ...(extra.details ? { details: extra.details } : {}),
+        ...(extra.cause !== undefined ? { cause: extra.cause } : {}),
+    };
+}
+/** HTTP status code 映射 —— Console route 层用。 */
+export function toHttpStatus(e) {
+    switch (e.kind) {
+        case 'not-found':
+            return 404;
+        case 'conflict':
+        case 'precondition':
+            return 409;
+        case 'validation':
+            return 422;
+        case 'external':
+            return 502;
+        case 'internal':
+            return 500;
+    }
+}
+/** CLI exit code 映射 —— CLI command 层用。 */
+export function toExitCode(e) {
+    switch (e.kind) {
+        case 'validation':
+        case 'precondition':
+            return 2;
+        case 'external':
+            return 3;
+        case 'not-found':
+        case 'conflict':
+        case 'internal':
+            return 1;
+    }
+}
+export function toProblemJson(e) {
+    return {
+        type: e.kind,
+        title: titleFor(e.kind),
+        status: toHttpStatus(e),
+        detail: e.message,
+        code: e.code,
+        ...(e.details ? { details: e.details } : {}),
+    };
+}
+function titleFor(kind) {
+    switch (kind) {
+        case 'not-found':
+            return 'Not Found';
+        case 'conflict':
+            return 'Conflict';
+        case 'precondition':
+            return 'Precondition Failed';
+        case 'validation':
+            return 'Validation Error';
+        case 'external':
+            return 'External Service Error';
+        case 'internal':
+            return 'Internal Error';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA4BH,qEAAqE;AACrE,MAAM,UAAU,WAAW,CACzB,IAAqB,EACrB,IAAY,EACZ,OAAe,EACf,QAAgE,EAAE;IAElE,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,OAAO;QACP,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,YAAY,CAAC,CAAc;IACzC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,WAAW;YACd,OAAO,GAAG,CAAC;QACb,KAAK,UAAU,CAAC;QAChB,KAAK,cAAc;YACjB,OAAO,GAAG,CAAC;QACb,KAAK,YAAY;YACf,OAAO,GAAG,CAAC;QACb,KAAK,UAAU;YACb,OAAO,GAAG,CAAC;QACb,KAAK,UAAU;YACb,OAAO,GAAG,CAAC;IACf,CAAC;AACH,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,UAAU,CAAC,CAAc;IACvC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,YAAY,CAAC;QAClB,KAAK,cAAc;YACjB,OAAO,CAAC,CAAC;QACX,KAAK,UAAU;YACb,OAAO,CAAC,CAAC;QACX,KAAK,WAAW,CAAC;QACjB,KAAK,UAAU,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAeD,MAAM,UAAU,aAAa,CAAC,CAAc;IAC1C,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;QACvB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;QACvB,MAAM,EAAE,CAAC,CAAC,OAAO;QACjB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,IAAqB;IACrC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,WAAW;YACd,OAAO,WAAW,CAAC;QACrB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,cAAc;YACjB,OAAO,qBAAqB,CAAC;QAC/B,KAAK,YAAY;YACf,OAAO,kBAAkB,CAAC;QAC5B,KAAK,UAAU;YACb,OAAO,wBAAwB,CAAC;QAClC,KAAK,UAAU;YACb,OAAO,gBAAgB,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/shared/result.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module        shared/result
+ * @description   Result<T, E> —— Service 层约定返回的容器类型
+ *
+ * @layer         shared
+ *
+ * Service 方法不抛业务异常 —— 用 Result 表达"成功 + 值"或"失败 + 结构化错误"。
+ * `throw` 保留给真正的系统问题（OOM / 断言违反 / 库 panic）。
+ */
+import type { DomainError } from './errors.js';
+export type Result<T, E = DomainError> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/** 包装成功结果。 */
+export declare function ok<T>(value: T): Result<T, never>;
+/** 包装失败结果。 */
+export declare function err<E>(error: E): Result<never, E>;
+/** 类型守卫：Result 是 Ok？ */
+export declare function isOk<T, E>(r: Result<T, E>): r is {
+    ok: true;
+    value: T;
+};
+/** 类型守卫：Result 是 Err？ */
+export declare function isErr<T, E>(r: Result<T, E>): r is {
+    ok: false;
+    error: E;
+};
+/**
+ * 成功时 map 值；失败时原样传递。
+ * 不改变 error 类型。
+ */
+export declare function mapOk<T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E>;
+/**
+ * 失败时 map 错误；成功时原样传递。
+ */
+export declare function mapErr<T, E, F>(r: Result<T, E>, f: (e: E) => F): Result<T, F>;
+/**
+ * 对 Ok 执行会返回 Result 的下一步（链式）。
+ * 任一步失败短路。
+ */
+export declare function andThen<T, U, E>(r: Result<T, E>, f: (t: T) => Promise<Result<U, E>>): Promise<Result<U, E>>;
+/**
+ * 取 Ok 值，不是 Ok 就抛 —— 仅用于测试 / 边界场景。
+ * 生产代码应该用 isOk + 分支处理。
+ */
+export declare function unwrap<T, E>(r: Result<T, E>, ctx?: string): T;
+//# sourceMappingURL=result.d.ts.map

package/dist/shared/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/shared/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,WAAW,IACjC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE9C,cAAc;AACd,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAEhD;AAED,cAAc;AACd,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEjD;AAED,wBAAwB;AACxB,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAEvE;AAED,yBAAyB;AACzB,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAEzE;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAE5E;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAE7E;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACnC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACf,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAEvB;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,CAM7D"}

package/dist/shared/result.js

@@ -0,0 +1,48 @@
+/** 包装成功结果。 */
+export function ok(value) {
+    return { ok: true, value };
+}
+/** 包装失败结果。 */
+export function err(error) {
+    return { ok: false, error };
+}
+/** 类型守卫：Result 是 Ok？ */
+export function isOk(r) {
+    return r.ok;
+}
+/** 类型守卫：Result 是 Err？ */
+export function isErr(r) {
+    return !r.ok;
+}
+/**
+ * 成功时 map 值；失败时原样传递。
+ * 不改变 error 类型。
+ */
+export function mapOk(r, f) {
+    return r.ok ? ok(f(r.value)) : r;
+}
+/**
+ * 失败时 map 错误；成功时原样传递。
+ */
+export function mapErr(r, f) {
+    return r.ok ? r : err(f(r.error));
+}
+/**
+ * 对 Ok 执行会返回 Result 的下一步（链式）。
+ * 任一步失败短路。
+ */
+export async function andThen(r, f) {
+    return r.ok ? await f(r.value) : r;
+}
+/**
+ * 取 Ok 值，不是 Ok 就抛 —— 仅用于测试 / 边界场景。
+ * 生产代码应该用 isOk + 分支处理。
+ */
+export function unwrap(r, ctx) {
+    if (!r.ok) {
+        const prefix = ctx ? `${ctx}: ` : '';
+        throw new Error(`${prefix}unwrap on Err: ${JSON.stringify(r.error)}`);
+    }
+    return r.value;
+}
+//# sourceMappingURL=result.js.map

package/dist/shared/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/shared/result.ts"],"names":[],"mappings":"AAeA,cAAc;AACd,MAAM,UAAU,EAAE,CAAI,KAAQ;IAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,cAAc;AACd,MAAM,UAAU,GAAG,CAAI,KAAQ;IAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,wBAAwB;AACxB,MAAM,UAAU,IAAI,CAAO,CAAe;IACxC,OAAO,CAAC,CAAC,EAAE,CAAC;AACd,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,KAAK,CAAO,CAAe;IACzC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAU,CAAe,EAAE,CAAc;IAC5D,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM,CAAU,CAAe,EAAE,CAAc;IAC7D,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,CAAe,EACf,CAAkC;IAElC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAO,CAAe,EAAE,GAAY;IACxD,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACV,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,kBAAkB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,CAAC,CAAC,KAAK,CAAC;AACjB,CAAC"}

package/dist/shared/runtimePaths.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 读 HOME —— 每次调用都重读环境变量，方便测试 mock。
+ * 缺 HOME 立即抛 —— 这是严重配置错误，别 silently fallback。
+ */
+export declare function home(): string;
+/** $HOME/.coral —— SPS 数据根目录 */
+export declare function coralRoot(): string;
+/** $HOME/.coral/console.lock —— Console 单实例锁文件 */
+export declare function consoleLockFile(): string;
+/** $HOME/.coral/env —— 全局环境变量文件 */
+export declare function globalEnvFile(): string;
+/** $HOME/.coral/sessions —— chat daemon unix socket 所在目录 */
+export declare function sessionsDir(): string;
+/** $HOME/.coral/chat-sessions —— chat 会话持久化目录 */
+export declare function chatSessionsDir(): string;
+/** $HOME/.coral/skills —— user-level skills */
+export declare function userSkillsDir(): string;
+/** $HOME/.coral/projects —— 项目根目录 */
+export declare function projectsDir(): string;
+/** $HOME/.coral/projects/<name> */
+export declare function projectDir(project: string): string;
+/** $HOME/.coral/projects/<name>/conf */
+export declare function projectConfFile(project: string): string;
+/** $HOME/.coral/projects/<name>/runtime */
+export declare function runtimeDir(project: string): string;
+/** $HOME/.coral/projects/<name>/runtime/state.json —— RuntimeStore 权威状态 */
+export declare function stateFile(project: string): string;
+/** $HOME/.coral/projects/<name>/runtime/supervisor.pid —— tick 进程 pid */
+export declare function supervisorPidFile(project: string): string;
+/**
+ * Worker marker 物理文件路径。
+ * @param project 项目名
+ * @param slotName slot 的完整字符串名（如 "worker-1"），不是数字
+ * @returns $HOME/.coral/projects/<project>/runtime/worker-<slotName>-current.json
+ *          即 worker-worker-N-current.json（双前缀）
+ */
+export declare function workerMarkerFile(project: string, slotName: string): string;
+/**
+ * 把数字 slot 转成 slotName（"worker-<N>"）—— 约定俗成。
+ * 当 UI / 外部 API 传数字时用这个规范化。
+ */
+export declare function slotNameFromNumber(slot: number): string;
+/**
+ * Worker marker 文件名的正则 —— 识别 runtime 目录里属于 marker 的文件。
+ * 匹配两种格式（兼容老数据）：
+ *   worker-worker-<N>-current.json   ← 现在的实际格式（slotName="worker-N"）
+ *   worker-<N>-current.json          ← 老兼容
+ * Capture group 1 是数字 slot（字符串形式）。
+ */
+export declare const WorkerMarkerFilenameRe: RegExp;
+/**
+ * 从文件名抽 slot 数字。非 marker 文件名返 null。
+ */
+export declare function slotFromMarkerFilename(filename: string): number | null;
+/** $HOME/.coral/projects/<name>/cards */
+export declare function cardsDir(project: string): string;
+/** $HOME/.coral/projects/<name>/cards/seq.txt —— 自增序列 */
+export declare function cardsSeqFile(project: string): string;
+/**
+ * $HOME/.coral/projects/<name>/cards/<state-lower-snake>
+ * state 做小写 + 非字母数字替成 '-' 的正规化（和 MarkdownTaskBackend 保持一致）。
+ */
+export declare function cardsStateDir(project: string, state: string): string;
+/** $HOME/.coral/projects/<name>/logs */
+export declare function logsDir(project: string): string;
+/** pipeline-<YYYY-MM-DD>.log 文件名 pattern */
+export declare const PipelineLogFilenameRe: RegExp;
+/** worker-<N> 标签在日志行里出现的 pattern，用于过滤 */
+export declare function workerLogLineTag(slot: number): string;
+/** $HOME/.coral/projects/<name>/pipelines */
+export declare function pipelinesDir(project: string): string;
+/** $HOME/.coral/projects/<name>/pipelines/project.yaml —— 活动 pipeline */
+export declare function activePipelineFile(project: string): string;
+/** 命名具体某个 pipeline yaml 文件 */
+export declare function pipelineFile(project: string, filename: string): string;
+/** pipeline yaml 文件名白名单正则 —— 防路径穿越 */
+export declare const PipelineFilenameRe: RegExp;
+//# sourceMappingURL=runtimePaths.d.ts.map

package/dist/shared/runtimePaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimePaths.d.ts","sourceRoot":"","sources":["../../src/shared/runtimePaths.ts"],"names":[],"mappings":"AAuCA;;;GAGG;AACH,wBAAgB,IAAI,IAAI,MAAM,CAM7B;AAED,gCAAgC;AAChC,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,kDAAkD;AAClD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,mCAAmC;AACnC,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,iDAAiD;AACjD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,+CAA+C;AAC/C,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,qCAAqC;AACrC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAID,mCAAmC;AACnC,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wCAAwC;AACxC,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,2CAA2C;AAC3C,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAA6C,CAAC;AAEjF;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtE;AAID,yCAAyC;AACzC,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpE;AAID,wCAAwC;AACxC,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB,QAAsC,CAAC;AAEzE,yCAAyC;AACzC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAID,6CAA6C;AAC7C,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,8BAA8B;AAC9B,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,sCAAsC;AACtC,eAAO,MAAM,kBAAkB,QAAwC,CAAC"}

package/dist/shared/runtimePaths.js

@@ -0,0 +1,179 @@
+/**
+ * @module        shared/runtimePaths
+ * @description   SPS 磁盘布局的唯一出处 —— 所有业务代码都从这里拼路径
+ *
+ * @layer         shared
+ *
+ * 解决 v0.49.5 / 15 / 16 反复踩到的"writer/reader 各自硬编码路径字符串"问题。
+ * 全仓业务代码禁止再出现 literal `.coral` / `runtime/` / `worker-*-current.json`。
+ *
+ * 目录布局（v0.49.16 当前）：
+ *   $HOME/.coral/
+ *   ├── console.lock            单实例 Console 锁
+ *   ├── env                     全局 env
+ *   ├── sessions/               chat daemon socket + sessions
+ *   ├── chat-sessions/
+ *   ├── skills/                 user-level skills
+ *   └── projects/<project>/
+ *       ├── conf                shell-export 项目配置
+ *       ├── cards/
+ *       │   ├── seq.txt         自增序列
+ *       │   └── <state>/        planning/backlog/todo/inprogress/qa/done
+ *       │       └── <seq>-<slug>.md
+ *       ├── pipelines/
+ *       │   ├── project.yaml    active pipeline
+ *       │   └── *.yaml          其它 preset
+ *       ├── runtime/
+ *       │   ├── state.json              RuntimeStore 权威状态
+ *       │   ├── supervisor.pid          tick 进程 pid
+ *       │   └── worker-<slotName>-current.json   marker（slotName="worker-N"，双前缀）
+ *       └── logs/
+ *           ├── pipeline-<date>.log
+ *           └── sps-acp-<project>-<slot>-acp-<ts>.log
+ *
+ * 所有以下常量 / builder / pattern 都是该布局的投影。改布局必须改这里。
+ */
+import { resolve } from 'node:path';
+// ─── Coral root ───────────────────────────────────────────────────
+/**
+ * 读 HOME —— 每次调用都重读环境变量，方便测试 mock。
+ * 缺 HOME 立即抛 —— 这是严重配置错误，别 silently fallback。
+ */
+export function home() {
+    const h = process.env.HOME;
+    if (!h) {
+        throw new Error('HOME environment variable not set — cannot resolve SPS paths');
+    }
+    return h;
+}
+/** $HOME/.coral —— SPS 数据根目录 */
+export function coralRoot() {
+    return resolve(home(), '.coral');
+}
+/** $HOME/.coral/console.lock —— Console 单实例锁文件 */
+export function consoleLockFile() {
+    return resolve(coralRoot(), 'console.lock');
+}
+/** $HOME/.coral/env —— 全局环境变量文件 */
+export function globalEnvFile() {
+    return resolve(coralRoot(), 'env');
+}
+/** $HOME/.coral/sessions —— chat daemon unix socket 所在目录 */
+export function sessionsDir() {
+    return resolve(coralRoot(), 'sessions');
+}
+/** $HOME/.coral/chat-sessions —— chat 会话持久化目录 */
+export function chatSessionsDir() {
+    return resolve(coralRoot(), 'chat-sessions');
+}
+/** $HOME/.coral/skills —— user-level skills */
+export function userSkillsDir() {
+    return resolve(coralRoot(), 'skills');
+}
+/** $HOME/.coral/projects —— 项目根目录 */
+export function projectsDir() {
+    return resolve(coralRoot(), 'projects');
+}
+// ─── Project layout ───────────────────────────────────────────────
+/** $HOME/.coral/projects/<name> */
+export function projectDir(project) {
+    return resolve(projectsDir(), project);
+}
+/** $HOME/.coral/projects/<name>/conf */
+export function projectConfFile(project) {
+    return resolve(projectDir(project), 'conf');
+}
+/** $HOME/.coral/projects/<name>/runtime */
+export function runtimeDir(project) {
+    return resolve(projectDir(project), 'runtime');
+}
+/** $HOME/.coral/projects/<name>/runtime/state.json —— RuntimeStore 权威状态 */
+export function stateFile(project) {
+    return resolve(runtimeDir(project), 'state.json');
+}
+/** $HOME/.coral/projects/<name>/runtime/supervisor.pid —— tick 进程 pid */
+export function supervisorPidFile(project) {
+    return resolve(runtimeDir(project), 'supervisor.pid');
+}
+// ─── Worker marker ────────────────────────────────────────────────
+// 这是 v0.49.16 踩最深的坑：slotName 形如 "worker-1"，拼出来就是
+// worker-worker-1-current.json（双 worker- 前缀）。此常量是唯一真相。
+/**
+ * Worker marker 物理文件路径。
+ * @param project 项目名
+ * @param slotName slot 的完整字符串名（如 "worker-1"），不是数字
+ * @returns $HOME/.coral/projects/<project>/runtime/worker-<slotName>-current.json
+ *          即 worker-worker-N-current.json（双前缀）
+ */
+export function workerMarkerFile(project, slotName) {
+    return resolve(runtimeDir(project), `worker-${slotName}-current.json`);
+}
+/**
+ * 把数字 slot 转成 slotName（"worker-<N>"）—— 约定俗成。
+ * 当 UI / 外部 API 传数字时用这个规范化。
+ */
+export function slotNameFromNumber(slot) {
+    return `worker-${slot}`;
+}
+/**
+ * Worker marker 文件名的正则 —— 识别 runtime 目录里属于 marker 的文件。
+ * 匹配两种格式（兼容老数据）：
+ *   worker-worker-<N>-current.json   ← 现在的实际格式（slotName="worker-N"）
+ *   worker-<N>-current.json          ← 老兼容
+ * Capture group 1 是数字 slot（字符串形式）。
+ */
+export const WorkerMarkerFilenameRe = /^worker-(?:worker-)?(\d+)-current\.json$/;
+/**
+ * 从文件名抽 slot 数字。非 marker 文件名返 null。
+ */
+export function slotFromMarkerFilename(filename) {
+    const m = filename.match(WorkerMarkerFilenameRe);
+    if (!m)
+        return null;
+    const n = Number.parseInt(m[1] ?? '', 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+// ─── Cards ────────────────────────────────────────────────────────
+/** $HOME/.coral/projects/<name>/cards */
+export function cardsDir(project) {
+    return resolve(projectDir(project), 'cards');
+}
+/** $HOME/.coral/projects/<name>/cards/seq.txt —— 自增序列 */
+export function cardsSeqFile(project) {
+    return resolve(cardsDir(project), 'seq.txt');
+}
+/**
+ * $HOME/.coral/projects/<name>/cards/<state-lower-snake>
+ * state 做小写 + 非字母数字替成 '-' 的正规化（和 MarkdownTaskBackend 保持一致）。
+ */
+export function cardsStateDir(project, state) {
+    const dirName = state.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    return resolve(cardsDir(project), dirName);
+}
+// ─── Logs ─────────────────────────────────────────────────────────
+/** $HOME/.coral/projects/<name>/logs */
+export function logsDir(project) {
+    return resolve(projectDir(project), 'logs');
+}
+/** pipeline-<YYYY-MM-DD>.log 文件名 pattern */
+export const PipelineLogFilenameRe = /^pipeline-\d{4}-\d{2}-\d{2}\.log$/;
+/** worker-<N> 标签在日志行里出现的 pattern，用于过滤 */
+export function workerLogLineTag(slot) {
+    return `worker-${slot}`;
+}
+// ─── Pipelines ────────────────────────────────────────────────────
+/** $HOME/.coral/projects/<name>/pipelines */
+export function pipelinesDir(project) {
+    return resolve(projectDir(project), 'pipelines');
+}
+/** $HOME/.coral/projects/<name>/pipelines/project.yaml —— 活动 pipeline */
+export function activePipelineFile(project) {
+    return resolve(pipelinesDir(project), 'project.yaml');
+}
+/** 命名具体某个 pipeline yaml 文件 */
+export function pipelineFile(project, filename) {
+    return resolve(pipelinesDir(project), filename);
+}
+/** pipeline yaml 文件名白名单正则 —— 防路径穿越 */
+export const PipelineFilenameRe = /^[a-zA-Z0-9_.-]+\.yaml(\.example)?$/;
+//# sourceMappingURL=runtimePaths.js.map

package/dist/shared/runtimePaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimePaths.js","sourceRoot":"","sources":["../../src/shared/runtimePaths.ts"],"names":[],"mappings":"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"}