@sema-agent/settings-schema 11.1.0 → 11.3.0

package/dist/shell-quote.js

@@ -0,0 +1,14 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):**一只** shell 引用 —— 命令行印出来、要让人粘贴去跑的命令里,路径一律过它。
+ *
+ * POSIX 单引号规则:整串包进 `'…'`,串里的 `'` 写成 `'\''`(结束引号 + 转义的引号 + 重新开引号);单引号里除 `'` 外一切字面,所以 `$` / 反引号 / 反斜杠 / 空格 /
+ * 换行都不再被 shell 解释。**只有安全字符集里的串原样返回、不加引号**:ASCII 字母数字与 `_ @ + : , . / -`。其余一律引用 —— 包括行首的 `~`(否则被展开成家目录)、
+ * `=`(zsh 里行首 `=cmd` 展开成命令路径)、`%`、通配符与非 ASCII(保守:引用永远安全,多包一层引号不会让命令失效)。空串写成 `''`(否则命令少一个参数)。
+ * 目标是 POSIX shell(sh / bash / zsh);Windows cmd.exe 不认单引号,不在范围内。
+ */
+const SHELL_SAFE = /^[A-Za-z0-9_@+:,./-]+$/;
+export function shellQuote(arg) {
+    if (SHELL_SAFE.test(arg))
+        return arg;
+    return `'${arg.replaceAll("'", "'\\''")}'`;
+}

package/dist/types.d.ts

@@ -32,19 +32,11 @@ export declare const ENV_NAME: z.ZodString;
  *  fs path — so the worker dies at exec/boot, not at config edit. A NUL is never legitimate in a command / path
  *  / host / image, so reject it on every exec-bound string field (mcp stdio + the whole remoteExec contract). R20. */
 export declare const hasNul: (s: string) => boolean;
-/** The params of a custom issue whose sentence QUOTES values (S-1075, 11.0.0) —— plain data: the sentence's fixed parts and the
- *  values between them, in order, so `message` is exactly {@link renderQuotedSentence} of them. A reader that has to treat the
- *  user-written parts of a sentence differently from its fixed words (a log boundary fingerprinting each value, the sanitizer
- *  bounding each value's length) reads them HERE instead of guessing where a value starts in the sentence. Every custom issue this
- *  package's schemas raise with a value in its sentence carries them (`issue.params`; a few fixed sentences raised through the same
- *  helpers carry them with no operands). */
-export interface QuotedIssueParams {
-    readonly template: readonly string[];
-    readonly operands: readonly (string | number)[];
-}
-/** The one rendering of a quoted sentence: `template[0] + show(operands[0]) + template[1] + … + template[n]`. `show` defaults to
- *  the value as written (that is how `message` is minted); a sanitizer / log boundary passes its own. */
-export declare function renderQuotedSentence(p: QuotedIssueParams, show?: (operand: string | number) => string): string;
+/** The params of a custom issue's sentence and their one rendering live in the package-private minting module `./quoted-issue`
+ *  (one minting point for the whole package); re-exported here unchanged. */
+export { renderQuotedSentence, type QuotedIssueParams } from "./quoted-issue.js";
+/** The one host-path shape judge (a task's `cwd`, a project's `folder` / `file` entries) lives in its leaf module `./host-path`. */
+export { ABSOLUTE_HOST_PATH_MAX, AbsoluteHostPath, isAbsoluteHostPath } from "./host-path.js";
 /** Does `s` contain a secret-shaped token? —— **the one scanner** (11.0.0, S-1274): the write side (this detector, behind every
  *  free-text write port — NON_SECRET_URL, mcp stdio, execution coords, ssh login, worker env, extraBody, …) and the display side
  *  (`redactSecrets`) read the SAME normalized forms ({@link secretScanForms} in the package-private `./secret-scan`: the raw string,
@@ -62,15 +54,16 @@ export declare function urlQueryFragmentHasSecret(u: URL): boolean;
 /** A URL handed to `fetch` that carries no credential: judged by THE URL shape judge ({@link httpUrlFlaws}, `./url-shape`) — a
  *  hierarchical http(s) URL with neither userinfo nor a fragment (an empty `#` included, 11.0.0) — and with no secret-shaped value
  *  in its path or query ({@link urlQueryFragmentHasSecret}). One issue per flaw, its message the judge's rule sentence (no value
- *  echoed; a fragment's also names its migration, {@link nonSecretUrlSentence}); `params.flaw` carries the rule word.
+ *  echoed; a fragment's also names its migration, {@link nonSecretUrlIssue}); `params` carries the sentence (`template` / `operands`,
+ *  no operands) and `flaw`, the rule word.
  *
- *  This is the seat of every URL in a stored DOMAIN document (models `baseUrl`, mcp `url`, `sessionMirror.engineUrl`, workers
- *  `gitApiBaseUrl`). A URL outside the domain documents — `remote-exec.json`'s endpoints, the web-admin credential envelope's
- *  `issuer` — uses {@link NON_SECRET_URL_NO_MIGRATION}.
+ *  This is the seat of every URL in a STORED document the one-time migration rewrites: the domain documents (models `baseUrl`, mcp `url`,
+ *  `sessionMirror.engineUrl`, workers `gitApiBaseUrl`) and `config.d/remote-exec.json` (k8s `apiUrl`, `s3Snapshot.endpoint`). A URL
+ *  that is not stored data — the web-admin credential envelope's `issuer`, a wire input — uses {@link NON_SECRET_URL_NO_MIGRATION}.
  *
  *  The value is kept EXACTLY as written: nothing here trims or normalizes it (zod's own `.url()` would hand back a rewritten string). */
 export declare const NON_SECRET_URL: z.ZodString;
-/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not a domain document): identical rules and rule
+/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not stored data): identical rules and rule
  *  sentences, but a fragment's refusal carries no migration signpost — pointing at a migration that cannot rewrite the value would
  *  send the operator to a command that does nothing for it. */
 export declare const NON_SECRET_URL_NO_MIGRATION: z.ZodString;
@@ -580,6 +573,27 @@ export declare const LimitsConfig: z.ZodObject<{
     toolResultTtlSec: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 export type LimitsConfig = z.infer<typeof LimitsConfig>;
+/** The autonomy ladder —— the closed set as a RUNTIME VALUE (same form as `REF_CHECKED_DOMAINS`): {@link AutonomyMode} (the zod enum)
+ *  and its type are DERIVED from this table, so a consumer that needs the words at runtime (an env parser, a catalog's enum column) imports
+ *  it instead of reaching into `GovernanceConfig.shape.autonomy.unwrap().options` or writing the four words again. */
+export declare const AUTONOMY_MODES: readonly ["read-only", "ask", "plan", "auto"];
+export type AutonomyMode = (typeof AUTONOMY_MODES)[number];
+/** `governance.autonomy`'s enum, derived from {@link AUTONOMY_MODES}. */
+export declare const AutonomyMode: z.ZodEnum<{
+    auto: "auto";
+    "read-only": "read-only";
+    ask: "ask";
+    plan: "plan";
+}>;
+/** A `commandPolicy[]` rule's decision —— the closed set as a RUNTIME VALUE; {@link CommandDecision} and its type are DERIVED from it. */
+export declare const COMMAND_DECISIONS: readonly ["allow", "ask", "deny"];
+export type CommandDecision = (typeof COMMAND_DECISIONS)[number];
+/** `commandPolicy[].decision`'s enum, derived from {@link COMMAND_DECISIONS}. */
+export declare const CommandDecision: z.ZodEnum<{
+    ask: "ask";
+    allow: "allow";
+    deny: "deny";
+}>;
 export declare const GovernanceConfig: z.ZodObject<{
     autonomy: z.ZodOptional<z.ZodEnum<{
         auto: "auto";
@@ -1094,6 +1108,35 @@ export type ExecutionPolicy = z.infer<typeof ExecutionPolicy>;
  *  flags:本常量刻意**不带** `i`,因为它是登记簿 Record 的**键**,大小写不同的同一个 UUID 会变成两条登记行
  *  (同一 project 双注册);引擎侧是识别语义(读 marker / 找回身份),放宽合理。 */
 export declare const PROJECT_ID_REGEX: RegExp;
+/** The bounds of a project registration's free-form fields —— the ONE source of these numbers: the schema below reads them, and so do
+ *  the server's project routes and the admin / client forms (they import this, never copy a number). The path bound of `folder` / `file`
+ *  entries is the host-path judge's own ({@link ABSOLUTE_HOST_PATH_MAX}). */
+export declare const PROJECT_LIMITS: {
+    readonly displayNameMax: 200;
+    readonly goalMax: 2000;
+    readonly contextItemsMax: 64;
+    readonly noteMax: 4000;
+};
+/** A project context item's kind —— the closed set as a RUNTIME VALUE: `folder` / `file` = a host path (judged by the same
+ *  {@link isAbsoluteHostPath} as a task's `cwd`), `note` = free text. */
+export declare const PROJECT_CONTEXT_ITEM_KINDS: readonly ["folder", "file", "note"];
+export type ProjectContextItemKind = (typeof PROJECT_CONTEXT_ITEM_KINDS)[number];
+/** A project's icon: a token (lowercase letter first, then lowercase letters / digits / `-`, at most 64). Absent = the default icon. */
+export declare const PROJECT_ICON_REGEX: RegExp;
+/** A project's colour: `#` + six lowercase hex digits. Absent = the default colour. */
+export declare const PROJECT_COLOR_REGEX: RegExp;
+/** One context item of a project. */
+export declare const ProjectContextItem: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"folder">;
+    value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"note">;
+    value: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type ProjectContextItem = z.infer<typeof ProjectContextItem>;
 export declare const ProjectRegistration: z.ZodObject<{
     displayName: z.ZodString;
     gitRemotes: z.ZodPrefault<z.ZodArray<z.ZodString>>;
@@ -1101,6 +1144,20 @@ export declare const ProjectRegistration: z.ZodObject<{
     registeredBy: z.ZodString;
     registeredAt: z.ZodString;
     notes: z.ZodOptional<z.ZodString>;
+    goal: z.ZodOptional<z.ZodString>;
+    contextItems: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"folder">;
+        value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"file">;
+        value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"note">;
+        value: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+    archivedAt: z.ZodOptional<z.ZodISODateTime>;
+    icon: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProjectRegistration = z.infer<typeof ProjectRegistration>;
 export declare const ProjectsConfig: z.ZodObject<{
@@ -1111,9 +1168,57 @@ export declare const ProjectsConfig: z.ZodObject<{
         registeredBy: z.ZodString;
         registeredAt: z.ZodString;
         notes: z.ZodOptional<z.ZodString>;
+        goal: z.ZodOptional<z.ZodString>;
+        contextItems: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"folder">;
+            value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"file">;
+            value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"note">;
+            value: z.ZodString;
+        }, z.core.$strip>], "kind">>>;
+        archivedAt: z.ZodOptional<z.ZodISODateTime>;
+        icon: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ProjectsConfig = z.infer<typeof ProjectsConfig>;
+/** The PATCH form of one registration: every key a PATCH may change, all optional; `registeredBy` / `registeredAt` (and any key
+ *  the registration does not have) are refused (`.strict()`). An optional key given `null` is cleared (merge-patch: `archivedAt: null`
+ *  un-archives). Each field is the registration's own schema — one bound, one shape. */
+export declare const ProjectRegistrationPatch: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    gitRemotes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    defaultScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    goal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    contextItems: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"folder">;
+        value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"file">;
+        value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"note">;
+        value: z.ZodString;
+    }, z.core.$strip>], "kind">>>>;
+    archivedAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ProjectRegistrationPatch = z.infer<typeof ProjectRegistrationPatch>;
+/**
+ * Apply a PATCH to one registration and judge the whole document with **the same** {@link ProjectsConfig} (the same remote-uniqueness rule a
+ * full write meets — a PATCH has no rule of its own). The patch is judged here by {@link ProjectRegistrationPatch} first — whatever the caller
+ * did before (a request body handed over as is cannot rewrite `registeredBy` / `registeredAt` or carry an unknown key) — and only its parsed
+ * keys are merged. The patched project is judged LAST, so a remote another project already holds is refused on the patched project and the
+ * sentence names the holder, whatever the document's key order; a successful result keeps the document's key order. Every issue path is a
+ * document coordinate (`["projects", <projectId>, …]`), the patch's own included. `projectId` must be registered (the caller answers "no such
+ * project" first) —— otherwise this throws.
+ */
+export declare function applyProjectPatch(doc: ProjectsConfig, projectId: string, patch: unknown): ReturnType<typeof ProjectsConfig.safeParse>;
 export declare const CollabTopology: z.ZodEnum<{
     star: "star";
     ring: "ring";
@@ -1874,12 +1979,14 @@ export declare const PluginsConfig: z.ZodObject<{
 export type PluginsConfig = z.infer<typeof PluginsConfig>;
 /** 提示声明的槽位闭集(core `PromptTextDeclaration.slot` 同形):identity = 角色卡、scenario = 场景说明、behavior = 行为守则。
  *  declaration 轴与 catalog 轴({@link PromptArtifactSection})共用这一只。 */
+export declare const PROMPT_SLOTS: readonly ["identity", "scenario", "behavior"];
+export type PromptSlot = (typeof PROMPT_SLOTS)[number];
+/** The slot enum, DERIVED from {@link PROMPT_SLOTS} (the runtime member table —— same form as `REF_CHECKED_DOMAINS`). */
 export declare const PromptSlot: z.ZodEnum<{
     scenario: "scenario";
     identity: "identity";
     behavior: "behavior";
 }>;
-export type PromptSlot = z.infer<typeof PromptSlot>;
 /** core `PromptTextDeclaration` 的契约层同形(core prompts/default.d.ts 逐字:id/slot 闭集/text)。
  *  slot ↔ 三卡:identity=角色卡、scenario=场景说明、behavior=行为守则([1051]①)。 */
 export declare const PromptTextDeclaration: z.ZodObject<{
@@ -2781,6 +2888,20 @@ export declare const DOMAIN_SCHEMAS: {
             registeredBy: z.ZodString;
             registeredAt: z.ZodString;
             notes: z.ZodOptional<z.ZodString>;
+            goal: z.ZodOptional<z.ZodString>;
+            contextItems: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"folder">;
+                value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"file">;
+                value: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"note">;
+                value: z.ZodString;
+            }, z.core.$strip>], "kind">>>;
+            archivedAt: z.ZodOptional<z.ZodISODateTime>;
+            icon: z.ZodOptional<z.ZodString>;
+            color: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>;
     readonly prompts: z.ZodObject<{
@@ -3027,4 +3148,3 @@ export declare const DOMAINS: DomainName[];
  *  filtering arbitrary keys (e.g. a `config.d/` directory scan that also turns up the non-domain
  *  `remote-exec.json`) — `remote-exec` is NOT a domain (it's the exec backend; see writeRemoteExec). */
 export declare function isDomainName(x: unknown): x is DomainName;
-export {};