evolcore 0.0.1 → 0.0.2

package/dist/config/role-service.js

@@ -0,0 +1,159 @@
+import fs from 'fs';
+import path from 'path';
+import { atomicReadJson, atomicWriteJson } from '../utils/atomic-write.js';
+import { agentRoleConfig, agentRolesIndex, kitsRoleTemplatesDir, resolvePaths } from '../paths.js';
+import { loadSchema } from './schema-registry.js';
+import { clearRoleStoreCache, getStoredRoleRegistry, isRoleName, readRoleStore, roleRegistryExists, } from './role-store.js';
+import { isManagementRole } from './builtin-roles.js';
+import { validateRoleConfig } from './role-schema.js';
+export class RoleServiceError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'RoleServiceError';
+    }
+}
+export function readRoleRegistry(selfAid) {
+    return getStoredRoleRegistry(selfAid);
+}
+export function readRoleDefinition(selfAid, roleId) {
+    return readRoleStore(selfAid).definitions[roleId] ?? null;
+}
+export function ensureInitialRoleRegistry(selfAid) {
+    if (roleRegistryExists(selfAid))
+        return false;
+    writeRoleRegistry(selfAid, {
+        $schema_version: 1,
+        roles: ['owner', 'admin', 'member', 'visitor'],
+        defaultRoles: { private: null, group: null },
+    });
+    return true;
+}
+export function writeRoleRegistry(selfAid, value) {
+    validateRegistry(selfAid, value);
+    const file = agentRolesIndex(selfAid);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteJson(file, { ...value, $schema_version: 1 });
+    clearRoleStoreCache(selfAid);
+}
+export function writeRoleDefinition(selfAid, roleId, value) {
+    if (!isRoleName(roleId))
+        throw new RoleServiceError('INVALID_ROLE_ID', `Invalid role id: ${roleId}`);
+    const normalized = { ...value, $schema_version: 1 };
+    validateRoleDefinition(normalized);
+    const registry = readRoleRegistry(selfAid);
+    if (!registry.roles.includes(roleId)) {
+        throw new RoleServiceError('ROLE_NOT_REGISTERED', `Role ${roleId} must be registered before writing its definition`);
+    }
+    const file = agentRoleConfig(selfAid, roleId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteJson(file, normalized);
+    clearRoleStoreCache(selfAid);
+}
+export function registerRole(selfAid, roleId, definition) {
+    if (!isRoleName(roleId))
+        throw new RoleServiceError('INVALID_ROLE_ID', `Invalid role id: ${roleId}`);
+    const registry = readRoleRegistry(selfAid);
+    if (registry.roles.includes(roleId))
+        throw new RoleServiceError('ROLE_EXISTS', `Role ${roleId} is already registered`);
+    writeRoleDefinitionFile(selfAid, roleId, definition);
+    try {
+        writeRoleRegistry(selfAid, { ...registry, roles: [...registry.roles, roleId] });
+    }
+    catch (error) {
+        try {
+            fs.rmSync(agentRoleConfig(selfAid, roleId), { force: true });
+        }
+        catch { }
+        throw error;
+    }
+}
+export function unregisterRole(selfAid, roleId) {
+    if (roleId === 'visitor' || isManagementRole(roleId)) {
+        throw new RoleServiceError('ROLE_PROTECTED', `Role ${roleId} cannot be unregistered`);
+    }
+    const registry = readRoleRegistry(selfAid);
+    if (!registry.roles.includes(roleId))
+        return;
+    const references = findRoleReferences(selfAid, roleId, registry);
+    if (references.length)
+        throw new RoleServiceError('ROLE_IN_USE', `Role ${roleId} is still referenced`, { references });
+    writeRoleRegistry(selfAid, { ...registry, roles: registry.roles.filter(item => item !== roleId) });
+    try {
+        fs.rmSync(agentRoleConfig(selfAid, roleId), { force: true });
+    }
+    catch { }
+    clearRoleStoreCache(selfAid);
+}
+export function listRoleDiagnostics(selfAid) {
+    return readRoleStore(selfAid).diagnostics;
+}
+function writeRoleDefinitionFile(selfAid, roleId, value) {
+    const normalized = { ...value, $schema_version: 1 };
+    validateRoleDefinition(normalized);
+    const file = agentRoleConfig(selfAid, roleId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteJson(file, normalized);
+}
+function validateRegistry(selfAid, value) {
+    const normalized = { ...value, $schema_version: 1 };
+    const schema = loadSchema('role-registry');
+    if (!schema.validate(normalized))
+        throw new RoleServiceError('SCHEMA_INVALID', formatSchemaErrors(schema.validate.errors));
+    const registry = normalized;
+    if (!registry.roles.includes('visitor'))
+        throw new RoleServiceError('VISITOR_REQUIRED', 'visitor must remain registered');
+    for (const role of ['private', 'group']) {
+        const selected = registry.defaultRoles[role];
+        if (selected !== null && (isManagementRole(selected) || !registry.roles.includes(selected))) {
+            throw new RoleServiceError('INVALID_DEFAULT_ROLE', `defaultRoles.${role} must reference an assignable registered role`);
+        }
+        if (selected !== null && !hasValidRoleDefinition(selfAid, selected)) {
+            throw new RoleServiceError('INVALID_DEFAULT_ROLE', `defaultRoles.${role} must reference a valid role definition`);
+        }
+    }
+}
+function hasValidRoleDefinition(selfAid, roleId) {
+    for (const file of [
+        agentRoleConfig(selfAid, roleId),
+        path.join(kitsRoleTemplatesDir(), `${roleId}.json`),
+    ]) {
+        try {
+            const value = atomicReadJson(file);
+            if (value !== null && validateRoleConfig(value).length === 0)
+                return true;
+        }
+        catch { }
+    }
+    return false;
+}
+function validateRoleDefinition(value) {
+    const issues = validateRoleConfig(value);
+    if (issues.length) {
+        throw new RoleServiceError('SCHEMA_INVALID', issues.map(issue => `${issue.field} ${issue.message}`).join('; '), { issues });
+    }
+}
+function findRoleReferences(selfAid, roleId, registry) {
+    const references = [];
+    if (registry.defaultRoles.private === roleId)
+        references.push('defaultRoles.private');
+    if (registry.defaultRoles.group === roleId)
+        references.push('defaultRoles.group');
+    const relations = path.join(resolvePaths().agentsDir, selfAid, 'relations');
+    if (!fs.existsSync(relations))
+        return references;
+    for (const entry of fs.readdirSync(relations, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const config = atomicReadJson(path.join(relations, entry.name, 'config.json'));
+        if (config?.role === roleId)
+            references.push(`relations/${entry.name}/role`);
+    }
+    return references;
+}
+function formatSchemaErrors(errors) {
+    return (errors ?? []).map(error => `${error.instancePath || '/'} ${error.message}`).join('; ');
+}

package/dist/config/role-store.js

@@ -0,0 +1,204 @@
+import fs from 'fs';
+import path from 'path';
+import { atomicReadJson } from '../utils/atomic-write.js';
+import { agentRoleConfig, agentRolesDir, agentRolesIndex, kitsRoleTemplatesDir, resolvePaths, } from '../paths.js';
+import { applyManagementRoleCeiling, getManagementRoleDefinition } from './builtin-roles.js';
+import { readBuiltinRoleTemplate } from './builtin-role-templates.js';
+import { loadSchema } from './schema-registry.js';
+import { validateRoleConfig } from './role-schema.js';
+const ROLE_NAME_RE = /^[a-z0-9_-]+$/;
+const RESERVED_ROLES = new Set(['owner', 'admin']);
+const BUILTIN_ROLES = ['owner', 'admin', 'member', 'visitor'];
+const cache = new Map();
+export function clearRoleStoreCache(selfAid) {
+    if (selfAid)
+        cache.delete(selfAid);
+    else
+        cache.clear();
+}
+export function roleRegistryPath(selfAid) {
+    return agentRolesIndex(selfAid);
+}
+export function roleRegistryExists(selfAid) {
+    return fs.existsSync(agentRolesIndex(selfAid));
+}
+export function roleConfigPath(selfAid, roleId) {
+    return agentRoleConfig(selfAid, roleId);
+}
+export function isRoleName(value) {
+    return typeof value === 'string' && ROLE_NAME_RE.test(value);
+}
+export function readRoleStore(selfAid) {
+    const signature = storeSignature(selfAid);
+    const cached = cache.get(selfAid);
+    if (cached?.signature === signature)
+        return cached.snapshot;
+    const diagnostics = [];
+    const registry = readRegistry(selfAid, diagnostics);
+    const definitions = {};
+    for (const roleId of registry.roles) {
+        const definition = readDefinition(selfAid, roleId, diagnostics);
+        if (definition)
+            definitions[roleId] = definition;
+    }
+    const rolesDir = agentRolesDir(selfAid);
+    if (fs.existsSync(rolesDir)) {
+        for (const entry of fs.readdirSync(rolesDir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name === 'index.json')
+                continue;
+            const roleId = entry.name.slice(0, -'.json'.length);
+            if (!registry.roles.includes(roleId)) {
+                diagnostics.push({
+                    code: 'UNREGISTERED_ROLE_FILE',
+                    roleId,
+                    file: path.relative(resolvePaths().root, path.join(rolesDir, entry.name)),
+                    message: `Role file ${entry.name} is not registered in roles/index.json`,
+                });
+            }
+        }
+    }
+    const snapshot = { registry, definitions, diagnostics };
+    cache.set(selfAid, { signature, snapshot });
+    return snapshot;
+}
+export function getStoredRoleDefinition(selfAid, roleId) {
+    if (!selfAid) {
+        if (roleId === 'owner' || roleId === 'admin')
+            return getManagementRoleDefinition(roleId);
+        return readBuiltinRoleTemplate(roleId).definition;
+    }
+    const snapshot = readRoleStore(selfAid);
+    if (roleId === 'owner' || roleId === 'admin') {
+        return applyManagementRoleCeiling(roleId, snapshot.definitions[roleId]);
+    }
+    if (!snapshot.registry.roles.includes(roleId))
+        return null;
+    return snapshot.definitions[roleId] ?? null;
+}
+export function getStoredRoleRegistry(selfAid) {
+    return readRoleStore(selfAid).registry;
+}
+export function roleIsAssignable(selfAid, roleId) {
+    if (!roleId || !isRoleName(roleId) || RESERVED_ROLES.has(roleId))
+        return false;
+    const snapshot = readRoleStore(selfAid);
+    return snapshot.registry.roles.includes(roleId) && !!snapshot.definitions[roleId];
+}
+function readRegistry(selfAid, diagnostics) {
+    const file = agentRolesIndex(selfAid);
+    let raw;
+    try {
+        raw = atomicReadJson(file);
+    }
+    catch (error) {
+        diagnostics.push({
+            code: 'INVALID_ROLE_REGISTRY',
+            file: path.relative(resolvePaths().root, file),
+            message: `Role registry contains invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return fallbackRegistry();
+    }
+    if (raw !== null) {
+        const schema = loadSchema('role-registry');
+        if (schema.validate(raw)) {
+            const value = raw;
+            const roles = [...new Set(value.roles)];
+            const defaultRoles = { ...value.defaultRoles };
+            for (const scene of ['private', 'group']) {
+                const selected = defaultRoles[scene];
+                if (selected === null || (roles.includes(selected) && !RESERVED_ROLES.has(selected)))
+                    continue;
+                diagnostics.push({
+                    code: 'INVALID_ROLE_ASSIGNMENT',
+                    roleId: selected,
+                    file: path.relative(resolvePaths().root, file),
+                    message: `defaultRoles.${scene} references invalid or unregistered role ${selected}; using visitor fallback`,
+                });
+                defaultRoles[scene] = null;
+            }
+            return { ...value, roles, defaultRoles };
+        }
+        diagnostics.push({
+            code: 'INVALID_ROLE_REGISTRY',
+            file: path.relative(resolvePaths().root, file),
+            message: 'Role registry failed schema or cross-file validation',
+        });
+        return fallbackRegistry();
+    }
+    diagnostics.push({
+        code: 'MISSING_ROLE_REGISTRY',
+        file: path.relative(resolvePaths().root, file),
+        message: 'roles/index.json is required; run the v5 role configuration migration before serving runtime traffic',
+    });
+    return fallbackRegistry();
+}
+function fallbackRegistry() {
+    return { $schema_version: 1, roles: [...BUILTIN_ROLES], defaultRoles: { private: null, group: null } };
+}
+function readDefinition(selfAid, roleId, diagnostics) {
+    const local = agentRoleConfig(selfAid, roleId);
+    for (const file of [local]) {
+        let raw;
+        try {
+            raw = atomicReadJson(file);
+        }
+        catch (error) {
+            diagnostics.push({
+                code: 'INVALID_ROLE_FILE',
+                roleId,
+                file: path.relative(resolvePaths().root, file),
+                message: `Role definition ${roleId} contains invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            continue;
+        }
+        if (raw === null)
+            continue;
+        const issues = validateRoleConfig(raw);
+        if (issues.length === 0) {
+            const { $schema_version: _schemaVersion, ...definition } = raw;
+            return definition;
+        }
+        diagnostics.push({
+            code: file === local ? 'INVALID_ROLE_FILE' : 'INVALID_ROLE_FILE',
+            roleId,
+            file: path.relative(resolvePaths().root, file),
+            message: `Role definition ${roleId} failed validation: ${issues.map(issue => `${issue.field} ${issue.message}`).join('; ')}`,
+        });
+    }
+    const builtin = readBuiltinRoleTemplate(roleId);
+    if (builtin.definition)
+        return builtin.definition;
+    if (builtin.error && ['owner', 'admin', 'member', 'visitor'].includes(roleId)) {
+        diagnostics.push({
+            code: 'INVALID_ROLE_FILE',
+            roleId,
+            file: path.relative(resolvePaths().root, builtin.file),
+            message: `Role definition ${roleId} ${builtin.error}`,
+        });
+    }
+    diagnostics.push({ code: 'MISSING_ROLE_FILE', roleId, message: `No valid definition found for role ${roleId}` });
+    return null;
+}
+function storeSignature(selfAid) {
+    const files = [agentRolesIndex(selfAid)];
+    const dir = agentRolesDir(selfAid);
+    if (fs.existsSync(dir)) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith('.json'))
+                files.push(path.join(dir, entry.name));
+        }
+    }
+    for (const roleId of ['owner', 'admin', 'member', 'visitor']) {
+        const template = path.join(kitsRoleTemplatesDir(), `${roleId}.json`);
+        files.push(template);
+    }
+    return files.map(file => {
+        try {
+            const stat = fs.statSync(file);
+            return `${file}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+        }
+        catch {
+            return `${file}:missing`;
+        }
+    }).join('|');
+}

package/dist/config/roles.js

@@ -0,0 +1,55 @@
+import { getBuiltinRolesConfig, getManagementRoleDefinition, isManagementRole, isReservedRoleName, } from './builtin-roles.js';
+import { clearRoleStoreCache, getStoredRoleDefinition, readRoleStore, roleIsAssignable, } from './role-store.js';
+const ROLE_NAME_RE = /^[a-z0-9_-]+$/;
+export { getBuiltinRolesConfig };
+export function readRolesConfig(selfAid) {
+    const builtin = getBuiltinRolesConfig();
+    const stored = selfAid ? readRoleStore(selfAid) : null;
+    return {
+        $schema_version: builtin.$schema_version,
+        defaultRoles: stored?.registry.defaultRoles ?? builtin.defaultRoles,
+        roles: stored?.definitions ?? builtin.roles,
+    };
+}
+export function getRoleDefinition(role, selfAid) {
+    if (selfAid)
+        return getStoredRoleDefinition(selfAid, role);
+    if (isManagementRole(role))
+        return getManagementRoleDefinition(role);
+    const config = readRolesConfig();
+    return config.roles[role] || null;
+}
+export function getUserRoleDefinition(role, selfAid) {
+    if (isReservedRoleName(role))
+        return null;
+    const config = readRolesConfig(selfAid);
+    return config.roles[role] || null;
+}
+export function getFieldPermission(role, field, selfAid) {
+    const roleDef = getRoleDefinition(role, selfAid);
+    return roleDef?.permissions[field] ?? null;
+}
+export function getCommandPermissions(role, selfAid) {
+    const roleDef = getRoleDefinition(role, selfAid);
+    return roleDef?.commandPermissions || {};
+}
+export function clearRolesCache() {
+    clearRoleStoreCache();
+}
+export function isValidUserRoleName(role) {
+    return typeof role === 'string'
+        && ROLE_NAME_RE.test(role)
+        && !isReservedRoleName(role);
+}
+export function roleExists(role, selfAid) {
+    if (!role || !isValidUserRoleName(role))
+        return false;
+    return selfAid ? roleIsAssignable(selfAid, role) : !!getUserRoleDefinition(role);
+}
+export function normalizeDefaultRole(value, selfAid) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (typeof value !== 'string')
+        return null;
+    return roleExists(value, selfAid) ? value : null;
+}

package/dist/config/schema-registry.js

@@ -0,0 +1,154 @@
+/**
+ * schema-registry —— 配置 schema 的唯一加载入口（SSOT）。
+ *
+ * schema 文件位于 kits/schemas/，命名 `{逻辑名}.schema.{版本}.json`，随 npm 包分发。
+ * 每个字段带：
+ *   - 标准 JSON Schema `type`（ajv 校验用）
+ *   - `x-merge`：合并语义（scalar / list / dict），覆盖链类型驱动合并的依据
+ * schema 根带：
+ *   - `x-logical-name` / `x-scope`
+ *
+ * v3 设计：所有参数统一在 config.json，按作用域路由到对应层级。
+ */
+import fs from 'fs';
+import path from 'path';
+import Ajv from 'ajv';
+import { kitsSchemasDir } from '../paths.js';
+let _ajv = null;
+function ajv() {
+    if (!_ajv) {
+        _ajv = new Ajv({ allErrors: true, strict: false, useDefaults: false });
+    }
+    return _ajv;
+}
+let _meta = null;
+export function loadMeta() {
+    if (_meta)
+        return _meta;
+    const p = path.join(kitsSchemasDir(), '_meta.json');
+    _meta = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    return _meta;
+}
+/** 某 schema 的当前版本号（来自 _meta.json）。 */
+export function currentVersion(name) {
+    const meta = loadMeta();
+    const v = meta.schemas[name]?.currentVersion;
+    if (typeof v !== 'number')
+        throw new Error(`[schema] no currentVersion for "${name}" in _meta.json`);
+    return v;
+}
+/** 全部逻辑 schema 名（来自 _meta.json，键序）。 */
+export function listSchemaNames() {
+    return Object.keys(loadMeta().schemas);
+}
+/** 是否为已知逻辑 schema 名。 */
+export function isSchemaName(name) {
+    return Object.prototype.hasOwnProperty.call(loadMeta().schemas, name);
+}
+/**
+ * 顶层字段的 schema 声明默认值（`default` 关键字），无则 undefined。
+ * 仅覆盖顶层标量字段——嵌套路径的默认值不在此解析。
+ * 用于 `ec config get` 在各存储层都无值时回落展示出厂默认。
+ */
+export function fieldSchemaDefault(name, fieldPath) {
+    if (fieldPath.includes('.'))
+        return undefined;
+    const spec = loadSchema(name).fields.get(fieldPath);
+    return spec && 'default' in spec ? spec.default : undefined;
+}
+/** 某版本的 history 元信息（date/description），无则 undefined。 */
+export function schemaHistoryEntry(name, version) {
+    const entry = loadMeta().history.find(h => h.schema === name && h.version === version);
+    return entry ? { date: entry.date, description: entry.description } : undefined;
+}
+/** 扫描 kits/schemas/ 得到某 schema 磁盘上存在的版本号（升序）。 */
+export function listSchemaVersions(name) {
+    const prefix = `${name}.schema.`;
+    const suffix = '.json';
+    const versions = [];
+    for (const file of fs.readdirSync(kitsSchemasDir())) {
+        if (!file.startsWith(prefix) || !file.endsWith(suffix))
+            continue;
+        const middle = file.slice(prefix.length, file.length - suffix.length);
+        if (!/^\d+$/.test(middle))
+            continue;
+        versions.push(Number(middle));
+    }
+    return versions.sort((a, b) => a - b);
+}
+/** 读指定版本的原始 schema（解析为对象，用于内容展示，不做 ajv 编译）。 */
+export function readRawSchema(name, version) {
+    const file = schemaFilePath(name, version);
+    if (!fs.existsSync(file)) {
+        throw new Error(`[schema] no schema file for "${name}" v${version}`);
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+const _cache = new Map();
+function schemaFilePath(name, version) {
+    return path.join(kitsSchemasDir(), `${name}.schema.${version}.json`);
+}
+function extractFields(raw) {
+    const fields = new Map();
+    const props = raw.properties || {};
+    for (const [name, spec] of Object.entries(props)) {
+        if (name === '$schema_version')
+            continue;
+        const merge = spec['x-merge'] || inferMerge(spec);
+        fields.set(name, {
+            name,
+            type: spec.type,
+            merge,
+            enum: spec.enum,
+            default: spec.default,
+            description: spec.description,
+        });
+    }
+    return fields;
+}
+/** 无 x-merge 时按 JSON Schema type 兜底推断合并语义。 */
+function inferMerge(spec) {
+    if (spec.type === 'array')
+        return 'list';
+    if (spec.type === 'object')
+        return 'dict';
+    return 'scalar';
+}
+/** 加载指定版本的 schema entry（带 ajv 编译 + 字段表）。 */
+export function loadSchema(name, version) {
+    const ver = version ?? currentVersion(name);
+    const key = `${name}@${ver}`;
+    const cached = _cache.get(key);
+    if (cached)
+        return cached;
+    const file = schemaFilePath(name, ver);
+    const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const entry = {
+        logicalName: name,
+        version: ver,
+        scope: raw['x-scope'] || name,
+        raw,
+        validate: ajv().compile(raw),
+        fields: extractFields(raw),
+    };
+    _cache.set(key, entry);
+    return entry;
+}
+/** extra_backup 不得指向 .env（构建期校验）——遍历声明里的 pattern。 */
+export function assertExtraBackupNotEnv(extraBackup) {
+    if (!extraBackup)
+        return;
+    for (const e of extraBackup) {
+        const pat = (e.pattern || '').toLowerCase();
+        const pth = (e.path || '').toLowerCase();
+        if (pat.includes('.env') || pth.endsWith('.env') || pat === '*') {
+            throw new Error(`[schema] extra_backup 不得指向 .env: ${JSON.stringify(e)}`);
+        }
+    }
+}
+/** 测试用：清空缓存。 */
+export function _resetSchemaCache() {
+    _cache.clear();
+    _meta = null;
+    _ajv = null;
+}