@armadra/agent 0.0.0-stage → 0.3.0

package/dist/config/paths.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 目录解析（设计 §10.1、§11.1 第 5 步）。[B5]
+ *
+ * - 用户级配置目录：`AMA_CONFIG_DIR` > Windows `%APPDATA%\ama` > `$XDG_CONFIG_HOME/ama` > `~/.config/ama`。
+ * - 数据目录：`AMA_DATA_DIR` > Windows `%LOCALAPPDATA%\ama` > `$XDG_DATA_HOME/ama` > `~/.local/share/ama`。
+ * - 会话目录：`--session-dir` > profile.sessionDir > `<dataDir>/sessions`。
+ */
+import type { ResolvedPaths } from "../cli/runtime.js";
+export declare const CONFIG_FILE = "config.json";
+export declare const AUTH_FILE = "auth.json";
+export declare const HOOKS_FILE = "hooks.json";
+export declare const TRUST_FILE = "trust.json";
+export declare const KEYBINDINGS_FILE = "keybindings.json";
+/** 项目级目录名（`<cwd>/.ama/`）。 */
+export declare const PROJECT_DIR = ".ama";
+export interface PathEnv {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly platform?: NodeJS.Platform;
+    readonly home?: string;
+}
+/** 展开开头的 `~`。 */
+export declare function expandHome(path: string, options?: PathEnv): string;
+export declare function resolveConfigDir(options?: PathEnv): string;
+export declare function resolveDataDir(options?: PathEnv): string;
+export interface ResolvePathsInput extends PathEnv {
+    cwd: string;
+    /** `--session-dir`（相对 cwd）。 */
+    sessionDirFlag?: string | undefined;
+    /** profile.sessionDir（已校验为绝对路径）。 */
+    profileSessionDir?: string | undefined;
+}
+export declare function resolvePaths(input: ResolvePathsInput): ResolvedPaths;
+/** 建目录（0700）并确认可写；失败抛 StartupError（退出码 3）。 */
+export declare function ensureDir(dir: string, label: string): void;
+/** 第 5 步：建 configDir / dataDir / sessionDir。 */
+export declare function ensurePaths(paths: ResolvedPaths): void;
+export declare function userFile(paths: Pick<ResolvedPaths, "configDir">, name: string): string;
+export declare function projectFile(cwd: string, name: string): string;

package/dist/config/paths.js

@@ -0,0 +1,108 @@
+/**
+ * 目录解析（设计 §10.1、§11.1 第 5 步）。[B5]
+ *
+ * - 用户级配置目录：`AMA_CONFIG_DIR` > Windows `%APPDATA%\ama` > `$XDG_CONFIG_HOME/ama` > `~/.config/ama`。
+ * - 数据目录：`AMA_DATA_DIR` > Windows `%LOCALAPPDATA%\ama` > `$XDG_DATA_HOME/ama` > `~/.local/share/ama`。
+ * - 会话目录：`--session-dir` > profile.sessionDir > `<dataDir>/sessions`。
+ */
+import { accessSync, constants, mkdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { StartupError } from "../errors.js";
+/** 与 cli/exit-codes.ts 的 Config 相同；config 层不反向依赖 cli 的值。 */
+const EXIT_CONFIG = 3;
+export const CONFIG_FILE = "config.json";
+export const AUTH_FILE = "auth.json";
+export const HOOKS_FILE = "hooks.json";
+export const TRUST_FILE = "trust.json";
+export const KEYBINDINGS_FILE = "keybindings.json";
+/** 项目级目录名（`<cwd>/.ama/`）。 */
+export const PROJECT_DIR = ".ama";
+function envOf(options) {
+    return options.env ?? process.env;
+}
+function nonEmpty(value) {
+    return value !== undefined && value.trim() !== "" ? value : undefined;
+}
+function homeOf(options) {
+    const env = envOf(options);
+    return options.home ?? nonEmpty(env["HOME"]) ?? nonEmpty(env["USERPROFILE"]) ?? homedir();
+}
+/** 展开开头的 `~`。 */
+export function expandHome(path, options = {}) {
+    if (path === "~")
+        return homeOf(options);
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(homeOf(options), path.slice(2));
+    return path;
+}
+export function resolveConfigDir(options = {}) {
+    const env = envOf(options);
+    const explicit = nonEmpty(env["AMA_CONFIG_DIR"]);
+    if (explicit !== undefined)
+        return resolve(expandHome(explicit, options));
+    if ((options.platform ?? process.platform) === "win32") {
+        const appData = nonEmpty(env["APPDATA"]);
+        if (appData !== undefined)
+            return join(appData, "ama");
+    }
+    const xdg = nonEmpty(env["XDG_CONFIG_HOME"]);
+    if (xdg !== undefined && isAbsolute(xdg))
+        return join(xdg, "ama");
+    return join(homeOf(options), ".config", "ama");
+}
+export function resolveDataDir(options = {}) {
+    const env = envOf(options);
+    const explicit = nonEmpty(env["AMA_DATA_DIR"]);
+    if (explicit !== undefined)
+        return resolve(expandHome(explicit, options));
+    if ((options.platform ?? process.platform) === "win32") {
+        const local = nonEmpty(env["LOCALAPPDATA"]);
+        if (local !== undefined)
+            return join(local, "ama");
+    }
+    const xdg = nonEmpty(env["XDG_DATA_HOME"]);
+    if (xdg !== undefined && isAbsolute(xdg))
+        return join(xdg, "ama");
+    return join(homeOf(options), ".local", "share", "ama");
+}
+export function resolvePaths(input) {
+    const configDir = resolveConfigDir(input);
+    const dataDir = resolveDataDir(input);
+    const cwd = resolve(input.cwd);
+    let sessionDir;
+    if (input.sessionDirFlag !== undefined) {
+        sessionDir = resolve(cwd, expandHome(input.sessionDirFlag, input));
+    }
+    else if (input.profileSessionDir !== undefined) {
+        sessionDir = resolve(input.profileSessionDir);
+    }
+    else {
+        sessionDir = join(dataDir, "sessions");
+    }
+    return { configDir, dataDir, sessionDir, cwd };
+}
+/** 建目录（0700）并确认可写；失败抛 StartupError（退出码 3）。 */
+export function ensureDir(dir, label) {
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (!statSync(dir).isDirectory())
+            throw new Error("不是目录");
+        accessSync(dir, constants.W_OK);
+    }
+    catch (error) {
+        throw new StartupError("config_invalid", `${label}不可写：${dir}（${error instanceof Error ? error.message : String(error)}）`, EXIT_CONFIG, { cause: error });
+    }
+}
+/** 第 5 步：建 configDir / dataDir / sessionDir。 */
+export function ensurePaths(paths) {
+    ensureDir(paths.configDir, "配置目录");
+    ensureDir(paths.dataDir, "数据目录");
+    ensureDir(paths.sessionDir, "会话目录");
+}
+export function userFile(paths, name) {
+    return join(paths.configDir, name);
+}
+export function projectFile(cwd, name) {
+    return join(cwd, PROJECT_DIR, name);
+}

package/dist/config/profile.d.ts

@@ -0,0 +1,27 @@
+/**
+ * profile.json（宿主用，设计 §10.3、§11.1 第 3 步、§11.2）。[B5]
+ *
+ * profile 的字段等价于对应命令行参数；命令行显式参数优先（合并在 cli/bootstrap.ts）。
+ * 文件不存在 / 版本不符 / 路径不是绝对路径 → StartupError（退出码 3）。profile 不含密钥。
+ */
+import type { AmaConfig } from "./types.js";
+/** profile 展开后的等价参数（全部为绝对路径）。 */
+export interface ProfileOptions {
+    path: string;
+    host?: string;
+    instructions: string[];
+    skillDirs: string[];
+    promptDirs: string[];
+    hooksFile?: string;
+    authFile?: string;
+    /** false：key 只来自 authFile。 */
+    authEnv: boolean;
+    sessionDir?: string;
+    /** profile.config 文件路径。 */
+    configFile?: string;
+    /** profile.config 的内容（已校验）。 */
+    config?: AmaConfig;
+    trustProject: boolean;
+    warnings: string[];
+}
+export declare function loadProfile(path: string, cwd?: string): ProfileOptions;

package/dist/config/profile.js

@@ -0,0 +1,65 @@
+/**
+ * profile.json（宿主用，设计 §10.3、§11.1 第 3 步、§11.2）。[B5]
+ *
+ * profile 的字段等价于对应命令行参数；命令行显式参数优先（合并在 cli/bootstrap.ts）。
+ * 文件不存在 / 版本不符 / 路径不是绝对路径 → StartupError（退出码 3）。profile 不含密钥。
+ */
+import { isAbsolute, resolve } from "node:path";
+import { StartupError } from "../errors.js";
+import { loadConfigFile } from "./load.js";
+import { PROFILE_PATH_FIELDS, PROFILE_PATH_LIST_FIELDS } from "./schema.js";
+const EXIT_CONFIG = 3;
+export function loadProfile(path, cwd = process.cwd()) {
+    const abs = resolve(cwd, path);
+    const loaded = loadConfigFile("profile", abs, { required: true });
+    if (loaded === undefined) {
+        throw new StartupError("profile_invalid", `${abs}: 文件不存在`, EXIT_CONFIG);
+    }
+    const profile = loaded.value;
+    const relative = [];
+    for (const key of PROFILE_PATH_FIELDS) {
+        const value = profile[key];
+        if (value !== undefined && !isAbsolute(value))
+            relative.push(`${key}: ${value}`);
+    }
+    for (const key of PROFILE_PATH_LIST_FIELDS) {
+        for (const value of profile[key] ?? []) {
+            if (!isAbsolute(value))
+                relative.push(`${key}: ${value}`);
+        }
+    }
+    if (relative.length > 0) {
+        throw new StartupError("profile_invalid", `${abs}: profile 中的路径必须是绝对路径：\n  ${relative.join("\n  ")}`, EXIT_CONFIG);
+    }
+    const options = profileToOptions(abs, profile, loaded.warnings);
+    if (profile.config !== undefined) {
+        const config = loadConfigFile("config", profile.config, { required: true });
+        if (config !== undefined) {
+            options.config = config.value;
+            options.warnings.push(...config.warnings);
+        }
+    }
+    return options;
+}
+function profileToOptions(path, profile, warnings) {
+    const options = {
+        path,
+        instructions: [...(profile.instructions ?? [])],
+        skillDirs: [...(profile.skillDirs ?? [])],
+        promptDirs: [...(profile.promptDirs ?? [])],
+        authEnv: profile.authEnv !== false,
+        trustProject: profile.trustProject === true,
+        warnings: [...warnings],
+    };
+    if (profile.host !== undefined)
+        options.host = profile.host;
+    if (profile.hooksFile !== undefined)
+        options.hooksFile = profile.hooksFile;
+    if (profile.authFile !== undefined)
+        options.authFile = profile.authFile;
+    if (profile.sessionDir !== undefined)
+        options.sessionDir = profile.sessionDir;
+    if (profile.config !== undefined)
+        options.configFile = profile.config;
+    return options;
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 配置文件校验（设计 §10、§6.1、§7.3）。[B5]
+ *
+ * 形状定义在 config/types.ts（B0）与 hooks/types.ts（HookConfig）；这里只做校验并再导出。
+ * 校验结果是诊断列表：`severity: "error"` 拒绝该文件（启动退出码 3），`"warning"` 只提示
+ * （未知字段等）。`path` 是 JSON 指针风格的字段路径（`permission.mode`、`hooks.PreToolUse[0]`）。
+ */
+import type { AmaConfig, AuthFile, ProfileFile, TrustFile } from "./types.js";
+import type { HookConfig } from "../hooks/types.js";
+export type { AmaConfig, AuthFile, ProfileFile, TrustFile, TrustEntry, ProviderConfig, PermissionConfig, CompactionConfig, RetryConfig, ToolsConfig, ToolsPreset, CodemodeConfig, CodemodeMode, HooksSettings, UiConfig, SkillsConfig, CacheConfig, ModelConfig, ModelOverride, ChannelConfig, } from "./types.js";
+export { CONFIG_FILE_VERSION } from "./types.js";
+export type { HookConfig } from "../hooks/types.js";
+export interface Diagnostic {
+    severity: "error" | "warning";
+    /** 字段路径；文件级问题为 ""。 */
+    path: string;
+    message: string;
+}
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh"];
+export declare const HOOK_TIMEOUT_MAX_MS = 600000;
+export declare function hasErrors(diagnostics: readonly Diagnostic[]): boolean;
+export declare function validateConfig(value: unknown): Diagnostic[];
+export declare function validateAuthFile(value: unknown): Diagnostic[];
+export declare const PROFILE_PATH_FIELDS: readonly ["host", "hooksFile", "authFile", "sessionDir", "config"];
+export declare const PROFILE_PATH_LIST_FIELDS: readonly ["instructions", "skillDirs", "promptDirs"];
+export declare function validateProfile(value: unknown): Diagnostic[];
+export declare function validateTrustFile(value: unknown): Diagnostic[];
+export declare function validateHookConfig(value: unknown): Diagnostic[];
+/** 校验通过后的类型断言（调用方保证 `hasErrors()` 为 false）。 */
+export declare function asConfig(value: unknown): AmaConfig;
+export declare function asAuthFile(value: unknown): AuthFile;
+export declare function asProfile(value: unknown): ProfileFile;
+export declare function asTrustFile(value: unknown): TrustFile;
+export declare function asHookConfig(value: unknown): HookConfig;