@dog_world/dak 0.1.0

package/dist/src/commands.js

@@ -0,0 +1,291 @@
+/** 命令工作流 */
+import { join } from 'node:path';
+import { readConfig, createDefaultConfig, validateConfigStore, writeConfigIfMissing } from './config.js';
+import { readState, writeState, writeStateIfMissing, upsertLinkRecord, removeLinkRecord, removeTargetState } from './state.js';
+import { scanResources, formatResourceList, ensureStoreLayout } from './resources.js';
+import { classifyTarget, linkItem, safeDeleteManagedLink } from './linker.js';
+import { RESOURCE_TYPES } from './types.js';
+/**
+ * 加载上下文（store/config/state）。
+ */
+async function loadContext(opts) {
+    const homeDir = opts.homeDir ?? process.env.HOME ?? '';
+    const storePath = opts.store ?? join(homeDir, '.dog-agents-kit');
+    const config = await readConfig(storePath);
+    validateConfigStore(config, storePath);
+    const state = await readState(storePath);
+    return { storePath, config, state, homeDir };
+}
+/**
+ * 解析目标名称（支持 all）。
+ */
+function resolveTargetNames(target, config) {
+    if (target === 'all') {
+        return Object.keys(config.targets ?? {});
+    }
+    if (!config.targets?.[target]) {
+        throw new Error(`unknown target: ${target}`);
+    }
+    return [target];
+}
+/**
+ * 获取目标 resource 路径（未配置则返回 null）。
+ */
+function targetResourcePath(config, targetName, resourceType) {
+    const t = config.targets?.[targetName];
+    if (!t?.resources?.[resourceType])
+        return null;
+    return join(t.path, t.resources[resourceType]);
+}
+/**
+ * 确定冲突策略。
+ */
+function selectedPolicy(opts, _target, _resource, _item) {
+    if (opts.conflictPolicy)
+        return opts.conflictPolicy;
+    if (opts.interactive && opts.chooseConflict) {
+        return opts.chooseConflict(_target, _resource, _item);
+    }
+    return 'skip';
+}
+/** ─── Commands ─── **/
+/** 初始化 store */
+export async function runInit(opts) {
+    const homeDir = opts.homeDir ?? process.env.HOME ?? '';
+    const storePath = opts.store ?? join(homeDir, '.dog-agents-kit');
+    const config = createDefaultConfig(storePath, homeDir);
+    await ensureStoreLayout(storePath, config);
+    await writeConfigIfMissing(storePath, config);
+    await writeStateIfMissing(storePath);
+    return `Initialized dak store at ${storePath}`;
+}
+/** 列出资源 */
+export async function runList(opts) {
+    const { storePath, config } = await loadContext(opts);
+    const resources = await scanResources(storePath, config);
+    return formatResourceList(resources);
+}
+/** 链接资源到目标 */
+export async function runLink(targetArg, opts) {
+    const { storePath, config, state, homeDir } = await loadContext(opts);
+    const targetNames = resolveTargetNames(targetArg, config);
+    const lines = [];
+    let linked = 0, created = 0, skipped = 0, conflicts = 0;
+    for (const tName of targetNames) {
+        for (const resourceType of RESOURCE_TYPES) {
+            const targetPath = targetResourcePath(config, tName, resourceType);
+            if (!targetPath)
+                continue; // target 未配置此 resource，跳过
+            const items = await scanResources(storePath, config);
+            for (const item of items[resourceType]) {
+                const itemTargetPath = join(targetPath, item.name);
+                const policy = selectedPolicy(opts, tName, resourceType, item.name);
+                const outcome = await linkItem({
+                    sourcePath: item.path,
+                    targetPath: itemTargetPath,
+                    resourceType,
+                    itemName: item.name,
+                    storePath,
+                    policy,
+                    now: opts.now,
+                });
+                // 写 state
+                if (outcome.record) {
+                    upsertLinkRecord(state, tName, resourceType, item.name, outcome.record);
+                }
+                let status = '';
+                switch (outcome.status) {
+                    case 'linked':
+                        status = 'linked';
+                        linked++;
+                        break;
+                    case 'created':
+                        status = 'created';
+                        created++;
+                        break;
+                    case 'backed-up':
+                        status = 'backed-up';
+                        created++;
+                        break;
+                    case 'overwritten':
+                        status = 'overwritten';
+                        created++;
+                        break;
+                    case 'conflict':
+                        status = 'conflict';
+                        conflicts++;
+                        break;
+                }
+                lines.push(`${tName} ${resourceType}/${item.name} ${status} ${itemTargetPath}`);
+            }
+        }
+    }
+    await writeState(storePath, state);
+    lines.push(`Summary: linked=${linked} created=${created} skipped=${skipped} conflicts=${conflicts}`);
+    return lines.join('\n');
+}
+/** 状态检查 */
+export async function runStatus(opts) {
+    const { storePath, config, state, homeDir } = await loadContext(opts);
+    const storeItems = await scanResources(storePath, config);
+    const lines = [];
+    for (const [tName, tState] of Object.entries(state.targets)) {
+        for (const resourceType of RESOURCE_TYPES) {
+            const targetPath = targetResourcePath(config, tName, resourceType);
+            if (!targetPath)
+                continue;
+            const records = tState[resourceType] ?? {};
+            const storeItemsForType = storeItems[resourceType] ?? [];
+            const storeItemMap = new Map(storeItemsForType.map(i => [i.name, i]));
+            // 当前 store 中的 items
+            for (const item of storeItemsForType) {
+                const itemTargetPath = join(targetPath, item.name);
+                const category = await classifyTarget(itemTargetPath, item.path);
+                lines.push(`${tName} ${resourceType}/${item.name} ${category} ${itemTargetPath}`);
+            }
+            // state 中已存在但 store 已删除（stale）
+            for (const [itemName, record] of Object.entries(records)) {
+                if (storeItemMap.has(itemName))
+                    continue;
+                const itemTargetPath = record.target;
+                lines.push(`${tName} ${resourceType}/${itemName} stale ${itemTargetPath}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/** 更新（补链接 + 清理 stale） */
+export async function runUpdate(opts) {
+    const { storePath, config, state, homeDir } = await loadContext(opts);
+    const lines = [];
+    let created = 0, deleted = 0, missingCount = 0, skipped = 0, conflicts = 0;
+    // target 集合只能来自 state.targets（已 link 过的 targets）
+    const targetNames = Object.keys(state.targets);
+    for (const tName of targetNames) {
+        const tState = state.targets[tName];
+        for (const resourceType of RESOURCE_TYPES) {
+            const targetPath = targetResourcePath(config, tName, resourceType);
+            if (!targetPath)
+                continue;
+            const records = { ...(tState[resourceType] ?? {}) };
+            // 1. 清理 stale
+            for (const [itemName, record] of Object.entries(records)) {
+                const sourcePath = record.source;
+                if (!existsSync(sourcePath)) {
+                    // stale：state 中有记录但 store 已无源
+                    const result = await safeDeleteManagedLink(record, storePath);
+                    switch (result) {
+                        case 'deleted':
+                            removeLinkRecord(state, tName, resourceType, itemName);
+                            deleted++;
+                            lines.push(`${tName} ${resourceType}/${itemName} deleted ${record.target}`);
+                            break;
+                        case 'missing':
+                            removeLinkRecord(state, tName, resourceType, itemName);
+                            missingCount++;
+                            lines.push(`${tName} ${resourceType}/${itemName} missing ${record.target}`);
+                            break;
+                        case 'conflict':
+                            conflicts++;
+                            lines.push(`${tName} ${resourceType}/${itemName} conflict ${record.target}`);
+                            break;
+                    }
+                }
+            }
+            // 2. 为当前 store item 补链接
+            const storeItems = await scanResources(storePath, config);
+            for (const item of storeItems[resourceType]) {
+                const itemTargetPath = join(targetPath, item.name);
+                const policy = selectedPolicy(opts, tName, resourceType, item.name);
+                const outcome = await linkItem({
+                    sourcePath: item.path,
+                    targetPath: itemTargetPath,
+                    resourceType,
+                    itemName: item.name,
+                    storePath,
+                    policy,
+                    now: opts.now,
+                });
+                if (outcome.record) {
+                    upsertLinkRecord(state, tName, resourceType, item.name, outcome.record);
+                }
+                switch (outcome.status) {
+                    case 'linked':
+                        skipped++;
+                        lines.push(`${tName} ${resourceType}/${item.name} linked ${itemTargetPath}`);
+                        break;
+                    case 'created':
+                        created++;
+                        lines.push(`${tName} ${resourceType}/${item.name} created ${itemTargetPath}`);
+                        break;
+                    case 'backed-up':
+                        created++;
+                        lines.push(`${tName} ${resourceType}/${item.name} backed-up ${itemTargetPath}`);
+                        break;
+                    case 'overwritten':
+                        created++;
+                        lines.push(`${tName} ${resourceType}/${item.name} overwritten ${itemTargetPath}`);
+                        break;
+                    case 'conflict':
+                        conflicts++;
+                        lines.push(`${tName} ${resourceType}/${item.name} conflict ${itemTargetPath}`);
+                        break;
+                }
+            }
+        }
+    }
+    await writeState(storePath, state);
+    lines.push(`Summary: created=${created} deleted=${deleted} missing=${missingCount} skipped=${skipped} conflicts=${conflicts}`);
+    return lines.join('\n');
+}
+/** 取消链接 */
+export async function runUnlink(targetArg, opts) {
+    const { storePath, state, homeDir } = await loadContext(opts);
+    const config = await readConfig(storePath);
+    const targetNames = resolveTargetNames(targetArg, config);
+    const lines = [];
+    let deleted = 0, missingCount = 0, conflicts = 0;
+    for (const tName of targetNames) {
+        const tState = state.targets[tName];
+        if (!tState)
+            continue;
+        for (const resourceType of RESOURCE_TYPES) {
+            const records = { ...(tState[resourceType] ?? {}) };
+            for (const [itemName, record] of Object.entries(records)) {
+                const result = await safeDeleteManagedLink(record, storePath);
+                switch (result) {
+                    case 'deleted':
+                        removeLinkRecord(state, tName, resourceType, itemName);
+                        deleted++;
+                        lines.push(`${tName} ${resourceType}/${itemName} deleted ${record.target}`);
+                        break;
+                    case 'missing':
+                        removeLinkRecord(state, tName, resourceType, itemName);
+                        missingCount++;
+                        lines.push(`${tName} ${resourceType}/${itemName} missing ${record.target}`);
+                        break;
+                    case 'conflict':
+                        conflicts++;
+                        lines.push(`${tName} ${resourceType}/${itemName} conflict ${record.target}`);
+                        break;
+                }
+            }
+        }
+        // 如果 target 下所有 records 都已删完，移除 target state
+        if (tState && Object.values(tState).every(m => Object.keys(m).length === 0)) {
+            removeTargetState(state, tName);
+        }
+    }
+    await writeState(storePath, state);
+    lines.push(`Summary: deleted=${deleted} missing=${missingCount} conflicts=${conflicts}`);
+    return lines.join('\n');
+}
+// existsSync 辅助（内联避免额外导入）
+function existsSync(p) {
+    try {
+        return require('node:fs').existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/config.js

@@ -0,0 +1,65 @@
+/** 配置读写与校验 */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_CONFIG, DEFAULT_STORE, CONFIG_FILE } from './constants.js';
+import { toAbsolutePath } from './paths.js';
+/**
+ * 解析 store 路径。
+ * @param storeArg CLI --store 参数
+ * @param homeDir 用户主目录
+ */
+export function resolveStorePath(storeArg, homeDir) {
+    const home = homeDir ?? process.env.HOME ?? '';
+    if (storeArg) {
+        return toAbsolutePath(storeArg, home, home);
+    }
+    return toAbsolutePath(DEFAULT_STORE, home, home);
+}
+/**
+ * 创建默认配置（内存对象，不写入磁盘）。
+ * @param storePath 绝对 store 路径
+ * @param homeDir 用户主目录
+ */
+export function createDefaultConfig(storePath, homeDir) {
+    const home = homeDir ?? process.env.HOME ?? '';
+    const targets = {};
+    for (const [name, t] of Object.entries(DEFAULT_CONFIG.targets)) {
+        targets[name] = {
+            path: toAbsolutePath(t.path, home, home),
+            resources: t.resources,
+        };
+    }
+    return { store: storePath, targets };
+}
+/**
+ * 从磁盘读取配置。
+ * @param storePath store 绝对路径
+ */
+export async function readConfig(storePath) {
+    const configPath = join(storePath, CONFIG_FILE);
+    const raw = await readFile(configPath, 'utf-8');
+    const config = JSON.parse(raw);
+    return config;
+}
+/**
+ * 仅当配置文件不存在时写入。
+ */
+export async function writeConfigIfMissing(storePath, config) {
+    const configPath = join(storePath, CONFIG_FILE);
+    if (existsSync(configPath))
+        return;
+    await mkdir(storePath, { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * 校验 config.store 与当前加载 store 是否一致。
+ * @throws 不一致时抛错
+ */
+export function validateConfigStore(config, storePath) {
+    const configStore = resolveStorePath(config.store);
+    const currentStore = resolveStorePath(storePath);
+    if (configStore !== currentStore) {
+        throw new Error('config store mismatch');
+    }
+}

package/dist/src/constants.js

@@ -0,0 +1,26 @@
+/** dak 常量定义 */
+/** 默认资源仓库目录 */
+export const DEFAULT_STORE = '~/.dog-agents-kit';
+/** 配置文件文件名 */
+export const CONFIG_FILE = 'dak.config.json';
+/** 状态文件名 */
+export const STATE_FILE = '.dak-state.json';
+/** 默认配置 */
+export const DEFAULT_CONFIG = {
+    store: DEFAULT_STORE,
+    targets: {
+        'codex': {
+            path: '~/.codex',
+            resources: { skills: 'skills', hooks: 'hooks', agents: 'agents' },
+        },
+        'claude-code': {
+            path: '~/.claude',
+            resources: { skills: 'skills', hooks: 'hooks', agents: 'agents' },
+        },
+    },
+};
+/** 空状态模板 */
+export const EMPTY_STATE = {
+    version: 1,
+    targets: {},
+};

package/dist/src/linker.js

@@ -0,0 +1,132 @@
+/** symlink 引擎与冲突策略 */
+import { mkdir, unlink, rename, lstat, realpath } from 'node:fs/promises';
+import { existsSync, symlinkSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { realParentJoined, isPathInside } from './paths.js';
+import { STATE_FILE } from './constants.js';
+/**
+ * 分类目标路径状态。
+ * 直接 lstat；broken symlink 的 lstat 成功（是 symlink）但 realpath 抛错。
+ */
+export async function classifyTarget(targetPath, expectedSource) {
+    try {
+        const linkStat = await lstat(targetPath);
+        if (!linkStat.isSymbolicLink())
+            return 'conflict';
+        try {
+            const realTarget = await realpath(targetPath);
+            if (realTarget === expectedSource)
+                return 'linked';
+            return 'conflict';
+        }
+        catch {
+            return 'broken';
+        }
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return 'missing';
+        throw e;
+    }
+}
+/**
+ * 创建相对 symlink（Linux/macOS）。
+ * Windows 目录 junction 另做处理，这里先实现相对 symlink。
+ */
+async function createRelativeSymlink(sourcePath, targetPath) {
+    const targetParent = await realParentJoined(dirname(targetPath));
+    const rel = relative(targetParent, sourcePath);
+    // 确保父目录存在
+    await mkdir(dirname(targetPath), { recursive: true });
+    // Windows 下目录 symlink 需要权限，这里统一用 symlink
+    symlinkSync(rel, targetPath);
+}
+/**
+ * 移动旧内容到备份目录。
+ * 备份根目录 = 目标 resource 根目录的父目录（即 target 根目录）下 .dak-backup
+ */
+async function moveToBackup(targetPath, storePath, resourceType, itemName, now) {
+    const ts = now.toISOString().replace(/[:.]/g, '-');
+    // targetPath = <targetRoot>/<resourceType>/<item>
+    // resource root parent = targetRoot = dirname(dirname(targetPath))
+    const targetRoot = dirname(dirname(targetPath));
+    const backupRoot = join(targetRoot, '.dak-backup');
+    const backupPath = join(backupRoot, ts, resourceType, itemName);
+    await mkdir(dirname(backupPath), { recursive: true });
+    await rename(targetPath, backupPath);
+    return backupPath;
+}
+/**
+ * 执行链接操作。
+ */
+export async function linkItem(input) {
+    const { sourcePath, targetPath, resourceType, itemName, storePath, policy, now } = input;
+    const category = await classifyTarget(targetPath, sourcePath);
+    if (category === 'linked') {
+        return { status: 'linked' };
+    }
+    const timestamp = now ?? new Date();
+    if (category === 'conflict' || category === 'broken') {
+        if (policy === 'skip') {
+            return { status: 'conflict' };
+        }
+        // 删除旧内容（broken symlink 或真实文件）
+        if (policy === 'backup') {
+            await moveToBackup(targetPath, storePath, resourceType, itemName, timestamp);
+        }
+        else if (policy === 'overwrite') {
+            try {
+                await unlink(targetPath);
+            }
+            catch {
+                // 可能不存在或已被删除，忽略
+            }
+        }
+    }
+    // 创建新链接
+    await createRelativeSymlink(sourcePath, targetPath);
+    const record = {
+        source: sourcePath,
+        target: targetPath,
+        linkedAt: timestamp.toISOString(),
+    };
+    return {
+        status: category === 'missing' ? 'created' : policy === 'backup' ? 'backed-up' : 'overwritten',
+        record,
+    };
+}
+/**
+ * 安全删除 dak 管理的 symlink。
+ * 仅当所有条件满足时删除：
+ * - target 存在且是 symlink
+ * - symlink 指向当前 store 内的路径
+ * - symlink 指向 record.source
+ */
+export async function safeDeleteManagedLink(record, storePath) {
+    const { target, source } = record;
+    if (!existsSync(target))
+        return 'missing';
+    try {
+        const linkStat = await lstat(target);
+        if (!linkStat.isSymbolicLink())
+            return 'conflict';
+    }
+    catch {
+        return 'conflict';
+    }
+    const realTarget = await realpath(target);
+    // 检查是否指向当前 store
+    if (!isPathInside(realTarget, storePath))
+        return 'conflict';
+    // 检查是否指向 record.source
+    if (realTarget !== source)
+        return 'conflict';
+    await unlink(target);
+    return 'deleted';
+}
+/**
+ * 获取 state 文件路径。
+ */
+export function statePathFor(storePath) {
+    return join(storePath, STATE_FILE);
+}

package/dist/src/paths.js

@@ -0,0 +1,147 @@
+/** 路径工具函数 */
+import { existsSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * 将路径中的 ~ 展开为用户主目录。
+ * @param input 输入路径
+ * @param homeDir 用户主目录绝对路径
+ * @returns 展开后的绝对路径
+ */
+export function expandHome(input, homeDir) {
+    if (input === '~')
+        return homeDir;
+    if (input.startsWith('~/'))
+        return homeDir + input.slice(1);
+    return input;
+}
+/**
+ * 将输入路径解析为绝对路径。
+ * 支持 ~ 展开、相对路径拼接、自动 normalize。
+ * @param input 输入路径（支持 ~ 前缀或相对路径）
+ * @param baseDir 相对路径的基准目录
+ * @param homeDir 用于 ~ 展开的主目录
+ * @returns 解析后的绝对路径
+ */
+export function toAbsolutePath(input, baseDir, homeDir) {
+    const expanded = expandHome(input, homeDir);
+    if (expanded.startsWith('/')) {
+        return resolve(expanded);
+    }
+    return resolve(baseDir, expanded);
+}
+/**
+ * 判断名称是否为隐藏项（以 . 开头）。
+ * @param name 文件/目录名称
+ * @returns 是否隐藏
+ */
+export function isHiddenItem(name) {
+    const base = dirname(name) === '.' ? name : name.split('/').pop() ?? name;
+    return base.startsWith('.');
+}
+/**
+ * 校验资源项名称是否合法。
+ * @param name 资源项名称
+ * @throws 名称非法时抛出错误
+ */
+export function assertSafeItemName(name) {
+    const base = dirname(name) === '.' ? name : name.split('/').pop() ?? name;
+    // 先检查 . 和 ..（它们是合法 hidden item，但应报 "Invalid"）
+    if (name === '.' || name === '..') {
+        throw new Error('Invalid resource item name');
+    }
+    if (isHiddenItem(base)) {
+        throw new Error('Hidden resource items are ignored');
+    }
+    if (name.includes('/') || name.includes('\\') || name.includes('.')) {
+        throw new Error('Invalid resource item name');
+    }
+    if (name === '..') {
+        throw new Error('Invalid resource item name');
+    }
+}
+/**
+ * 判断 child 路径是否在 parent 路径内部（严格前缀匹配，防止边界欺骗）。
+ * @param child 子路径
+ * @param parent 父路径
+ * @returns 是否在内部
+ */
+export function isPathInside(child, parent) {
+    const normalizedChild = resolve(child);
+    let normalizedParent = resolve(parent);
+    if (!normalizedParent.endsWith('/')) {
+        normalizedParent += '/';
+    }
+    // 子路径在父目录内（严格前缀）
+    if (normalizedChild.startsWith(normalizedParent))
+        return true;
+    // 子路径等于父目录本身
+    if (normalizedChild === parent || normalizedChild + '/' === normalizedParent)
+        return true;
+    return false;
+}
+/**
+ * 获取路径的可比较真实路径。
+ * 尝试 fs.realpath，失败时 fallback 到 path.resolve。
+ * @param input 输入路径
+ * @returns 绝对路径
+ */
+export async function realComparablePath(input) {
+    try {
+        return await realpath(input);
+    }
+    catch {
+        return resolve(input);
+    }
+}
+/**
+ * 解析 symlink 的实际目标路径。
+ * @param linkPath 链接文件的实际路径
+ * @param rawTarget 链接原始 target（相对或绝对）
+ * @returns 解析后的绝对目标路径
+ */
+export async function resolveLinkTarget(linkPath, rawTarget) {
+    if (rawTarget.startsWith('/')) {
+        return resolve(rawTarget);
+    }
+    const realParent = await realParentJoined(dirname(linkPath));
+    const resolved = join(realParent, rawTarget);
+    return resolve(resolved);
+}
+/**
+ * 获取路径的"真实父目录 + 剩余相对部分"拼接结果。
+ * 向上逐级查找最近存在的目录取 realpath，再拼接剩余部分。
+ * @param path 目标路径
+ * @returns 拼接后的绝对路径
+ */
+export async function realParentJoined(path) {
+    const dir = dirname(path);
+    const basename = path.split('/').pop() ?? '';
+    // 向上逐级查找最近存在的目录
+    let current = dir;
+    const segments = [];
+    let foundExisting = null;
+    let remainingSegments = [];
+    while (current !== segments.join('/')) {
+        if (existsSync(current)) {
+            foundExisting = current;
+            // 计算还需要拼接的部分
+            const dirSegments = dir.split('/').filter(Boolean);
+            const foundSegments = foundExisting.split('/').filter(Boolean);
+            remainingSegments = dirSegments.slice(foundSegments.length);
+            remainingSegments.push(basename);
+            break;
+        }
+        segments.unshift(current.split('/').pop() ?? '');
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    if (foundExisting) {
+        const realAncestor = await realpath(foundExisting);
+        const remaining = remainingSegments.join('/');
+        return join(realAncestor, remaining);
+    }
+    return resolve(path);
+}