@aalis/runtime 0.15.0 → 0.16.0

package/README.md

@@ -1,6 +1,6 @@
 # @aalis/runtime
 
-Aalis 独立部署运行时：node_modules 插件加载 + YAML 配置 + 一行启动 startAalis
+Aalis 独立部署运行时：node_modules 插件加载 + YAML 配置与密钥文件 + 一行启动 startAalis
 
 ## 安装
 
@@ -10,12 +10,21 @@ pnpm add @aalis/runtime
 
 ## 提供 / 依赖
 
-宿主组装件，不是插件，无 `provides` / `uses`；`startAalis` 在根上独占登记 `host-config`（`@aalis/api-host-config`）与 `plugin-source`（`@aalis/api-plugin-source`）两个服务。主要导出：`startAalis`、`createNodeModulesPluginLoader`、`createFsPluginLoader`、`createPluginDiscovery`、`createConfigStore`、`installHostConfig`、`withPluginConfigSync`、`createFsYamlConfigProvider`、`createProcessRespawnStrategy`。peer：`@aalis/core`（`>=0.17.0 <1.0.0`）。
+宿主组装件，不是插件，无 `provides` / `uses`；`startAalis` 在根上独占登记 `host-paths`（`@aalis/api-host-paths`）、`host-logs`（`@aalis/api-host-logs`）、`host-config`（`@aalis/api-host-config`）与 `plugin-source`（`@aalis/api-plugin-source`）四个服务。主要导出：`startAalis`、家目录的 `parseHostArgs` / `resolveHome` / `profileOfRealHome` / `derivePaths` / `isHomeInitialized` / `initHome`、`createNodeModulesPluginLoader`、`createFsPluginLoader`、`createPluginDiscovery`、`createConfigStore`、`installHostConfig`、`createHostLogs`、`withPluginConfigSync`、`createFsYamlConfigProvider`、`createFsSecretsProvider`、`createProcessRespawnStrategy`。peer：`@aalis/core`（`>=0.20.0 <1.0.0`）。
 
 ```ts
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { startAalis } from '@aalis/runtime';
+
+// 安装集是入口文件所在目录；家目录按 --home、AALIS_HOME、--profile 的顺序取，缺省 ~/.aalis
+startAalis({ appDir: dirname(fileURLToPath(import.meta.url)) });
 ```
 
+第一次运行前在启动命令里加上 `--init` 初始化家目录。
+
+配置里标了 `secret: true` 的字段，值存在家目录的 `secrets.yaml`（0600），`aalis.config.yaml` 只放引用 `{ $secret: '<键>' }`；写进主配置的明文在启动或热重载时自动移过去。备份家目录时连同 `secrets.yaml` 一起备份。
+
 ## 文档
 
 详见 [docs/architecture/runtime.md](../../docs/architecture/runtime.md)。

package/dist/config-store.d.ts

@@ -1,6 +1,8 @@
 import { type AalisConfig, type HostConfig } from '@aalis/api-host-config';
-import { type App } from '@aalis/core';
-import type { ConfigSyncOptions } from './config-sync.js';
+import { type App, type Services } from '@aalis/core';
+import { type ConfigSchema } from '@aalis/schema-config';
+import { type ConfigSyncOptions } from './config-sync.js';
+import { type ResolvedSecrets, type SplitSecrets } from './secrets.js';
 /**
  * 配置提供者：负责持久化层。文档由宿主在构造前自己加载好传入，provider 不必提供 load()。
  */
@@ -14,25 +16,60 @@ export interface ConfigProvider {
     /** 订阅外部对配置源的变更；返回 dispose */
     watch?(onChange: (next: AalisConfig) => void): () => void;
 }
+/** 密钥存储的持久化层（Node 宿主是家目录的 secrets.yaml）。约定同 {@link ConfigProvider} */
+export interface SecretProvider {
+    save?(values: Record<string, unknown>): void | Promise<void>;
+    watch?(onChange: (next: Record<string, unknown>) => void): () => void;
+}
 /**
- * 宿主持有的配置文档。读写方法与插件经 host-config 看到的相同；落盘与外部变更监听只给宿主：
- * `persist()` 是裸落盘，不记日志，兑现值表示是否交给了 provider 落盘（provider 不提供 save 时为 false），
- * 失败原样以拒绝传出。插件拿到的 `save()` 由 {@link installHostConfig}
- * 包上日志与「拒绝已处理」，两者名字不同，本对象因此不能被误当成 HostConfig 直接交出去。
+ * 宿主持有的配置文档。读写方法与插件经 host-config 看到的相同（写方法这里不检查形态，宿主自己的同步先拆后写）；
+ * 落盘、外部变更监听与密钥的换算只给宿主：
+ * `persist()` 是裸落盘，不记日志，先写密钥再写文档，兑现值表示文档是否交给了 provider 落盘（provider 不提供 save
+ * 时为 false），失败原样以拒绝传出。插件拿到的 `save()` 由 {@link installHostConfig} 包上日志与「拒绝已处理」，
+ * 两者名字不同，本对象因此不能被误当成 HostConfig 直接交出去。
  * 裁剪政策 `trimUnknownFields` 是宿主的同步政策、不属文档，同样由 {@link installHostConfig} 填入。
  */
-export interface ConfigStore extends Omit<HostConfig, 'save' | 'trimUnknownFields'> {
+export interface ConfigStore extends Omit<HostConfig, 'save' | 'trimUnknownFields' | 'applyPluginConfig'> {
     persist(): Promise<boolean>;
-    /** 订阅外部变更（新快照已过同一道闸替换进文档后回调）；单订阅者，返回退订 */
-    watch(onChange: () => void): () => void;
+    /**
+     * 订阅外部变更（配置文件或密钥文件；新内容已过同一道闸替换进来后回调，参数是替换前的文档）；单订阅者，返回退订。
+     * 密钥文件拒写之后的那次变更按文件对账，同主配置拒写：还没写成的密钥作废，文档退回配置文件上最后读入或写出的那一份
+     */
+    watch(onChange: (previous: Readonly<AalisConfig>) => void): () => void;
     unwatch(): void;
+    /** 宿主有没有密钥存储：没有时密钥照旧以明文留在文档里，不拆 */
+    readonly hasSecretStore: boolean;
+    /**
+     * 文档形态解析成运行态：`doc` 缺省取该实例在文档里的配置；`staged` 是还没提交的写入，优先于存储。
+     * 悬空的引用原样留着并列在 dangling 里
+     */
+    resolvePluginConfig(instanceId: string, schema: ConfigSchema | undefined, doc?: Record<string, unknown>, staged?: ReadonlyMap<string, unknown>): ResolvedSecrets;
+    /**
+     * 提交的配置拆成文档形态（见 secrets.ts 的 splitSecrets）。`base` 是改动前的文档，缺省取该实例当前的文档。
+     * 只暂存、不写存储；没有密钥存储时原样返回
+     */
+    splitPluginSecrets(instanceId: string, schema: ConfigSchema | undefined, submitted: Record<string, unknown>, base?: Record<string, unknown>): SplitSecrets;
+    /** 把暂存的写入提交进密钥存储，返回撤回函数（恢复写之前的值） */
+    commitSecrets(writes: ReadonlyMap<string, unknown>): () => void;
+}
+export interface SecretStoreInit {
+    values: Record<string, unknown>;
+    provider?: SecretProvider;
 }
-export declare function createConfigStore(initial: Partial<AalisConfig>, provider?: ConfigProvider): ConfigStore;
 /**
- * 把文档接到 App：以 host-config 服务独占登记在根激活上，应用文档里的服务偏好，
- * 并在服务上线时记录它有无用户偏好。须在注册任何插件之前调用，偏好才先于全部提供者生效。
+ * @param secrets 宿主的密钥存储；不给时没有密钥存储（嵌入式宿主、只在内存里的配置），密钥照旧以明文留在文档里
+ */
+export declare function createConfigStore(initial: Partial<AalisConfig>, provider?: ConfigProvider, secrets?: SecretStoreInit): ConfigStore;
+/**
+ * 把文档接到 App：以 host-config 服务独占登记在根激活上，应用文档里的服务偏好。
+ * 须在注册任何插件之前调用，偏好才先于全部提供者生效。
  * `opts` 传交给配置同步（withPluginConfigSync / installConfigHotReload）的同一份：host-config 的
  * `trimUnknownFields` 据此声明宿主的裁剪政策（缺省与配置同步一样按裁剪）。
  */
 export declare function installHostConfig(app: App, store: ConfigStore, opts?: ConfigSyncOptions): void;
+/**
+ * 文档里的服务偏好（全局与本插件）对到运行态：`previous` 是改动前的文档（热重载时给），这一份没有、它有的撤回，
+ * 没变的不动；不给时（启动）全部应用
+ */
+export declare function applyServicePreferences(live: Pick<Services, 'prefer' | 'unprefer'>, next: Readonly<AalisConfig>, previous?: Readonly<AalisConfig>): void;
 //# sourceMappingURL=config-store.d.ts.map

package/dist/config-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-store.d.ts","sourceRoot":"","sources":["../src/config-store.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAmC,MAAM,wBAAwB,CAAC;AAC5G,OAAO,EAAE,KAAK,GAAG,EAA6B,MAAM,aAAa,CAAC;AAElE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,6BAA6B;IAC7B,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACjF,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,0CAA0C;IAC1C,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACxC,OAAO,IAAI,IAAI,CAAC;CACjB;AAUD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,WAAW,CAmEvG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAiC9F"}
+{"version":3,"file":"config-store.d.ts","sourceRoot":"","sources":["../src/config-store.ts"],"names":[],"mappings":"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"}