@dog_world/dak 0.1.0

package/dist/config.js

@@ -0,0 +1,105 @@
+/** 配置读写与校验 */
+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 { DEFAULT_RESOURCE_TYPES } from './types.js';
+import { assertSafeItemName, toAbsolutePath } from './paths.js';
+/**
+ * 解析 config 声明的资源类型集合。
+ * 缺失或空时回退 DEFAULT_RESOURCE_TYPES。
+ */
+export function declaredResourceTypes(config) {
+    const types = config.resourceTypes ?? [...DEFAULT_RESOURCE_TYPES];
+    return types.length > 0 ? [...types] : [...DEFAULT_RESOURCE_TYPES];
+}
+/**
+ * 解析 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, resourceTypes: [...DEFAULT_RESOURCE_TYPES], targets };
+}
+/**
+ * 从磁盘读取配置并校验结构。
+ * 校验：targets 存在；resourceTypes 合法；target.resources key 必须在声明的 resourceTypes 内。
+ * store 顶层资源目录的布局由 ensureStoreLayout 保证，不在 readConfig 校验。
+ * @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);
+    validateConfigShape(config);
+    return config;
+}
+/**
+ * 校验 config 结构：targets 必须存在；resourceTypes 中每个类型名必须合法；
+ * target.resources 的 key 必须在声明的 resourceTypes 内。
+ * @throws 结构非法时抛错
+ */
+function validateConfigShape(config) {
+    if (!config || typeof config !== 'object' || !config.targets) {
+        throw new Error('Invalid config: targets missing');
+    }
+    const validResources = new Set(declaredResourceTypes(config));
+    for (const type of validResources) {
+        assertSafeItemName(type);
+    }
+    for (const [name, t] of Object.entries(config.targets)) {
+        if (!t || typeof t.path !== 'string') {
+            throw new Error(`Invalid config: target ${name} missing path`);
+        }
+        if (t.resources) {
+            for (const key of Object.keys(t.resources)) {
+                if (!validResources.has(key)) {
+                    throw new Error(`Invalid config: target ${name} has unknown resource type ${key}`);
+                }
+            }
+        }
+    }
+}
+/**
+ * 仅当配置文件不存在时写入。
+ */
+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 是否一致。
+ * 相对路径按 store 根目录解析；`~` 按当前命令 home 解析（计划全局约束）。
+ * @throws 不一致时抛错
+ */
+export function validateConfigStore(config, storePath, homeDir) {
+    const home = homeDir ?? process.env.HOME ?? '';
+    const configStore = toAbsolutePath(config.store, storePath, home);
+    const currentStore = toAbsolutePath(storePath, home, home);
+    if (configStore !== currentStore) {
+        throw new Error('config store mismatch');
+    }
+}

package/dist/constants.js

@@ -0,0 +1,23 @@
+/** dak 常量定义 */
+import { DEFAULT_RESOURCE_TYPES } from './types.js';
+/** 默认资源仓库目录 */
+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,
+    resourceTypes: [...DEFAULT_RESOURCE_TYPES],
+    targets: {
+        'codex': {
+            path: '~/.codex',
+            resources: { skills: 'skills', hooks: 'hooks', agents: 'agents' },
+        },
+        'claudecode': {
+            path: '~/.claude',
+            resources: { skills: 'skills', hooks: 'hooks', agents: 'agents' },
+        },
+    },
+};

package/dist/linker.js

@@ -0,0 +1,177 @@
+/** symlink 引擎与冲突策略 */
+import { mkdir, unlink, rename, lstat, readlink, stat } from 'node:fs/promises';
+import { symlinkSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { resolveLinkTarget, realParentJoined, isPathInside } from './paths.js';
+/**
+ * 解析 symlink 的逻辑目标绝对路径（不跟随 symlink，不依赖目标存在）。
+ * 用 readlink 取原始 target，再用 resolveLinkTarget 按链接父目录解析。
+ * 断链 symlink 也能解析，因为它不 stat 目标。
+ */
+async function logicalSymlinkTarget(linkPath) {
+    const raw = await readlink(linkPath);
+    return resolveLinkTarget(linkPath, raw);
+}
+/**
+ * 分类目标路径状态。
+ * - lstat 判存在：ENOENT → missing；非 symlink → conflict。
+ * - stat 跟随 symlink 判目标是否存在：不存在 → broken。
+ * - readlink 逻辑解析与 expectedSource 比较（不 realpath），避免 store 处于
+ *   symlink 后方时假 conflict：相等 → linked，否则 → conflict。
+ */
+export async function classifyTarget(targetPath, expectedSource) {
+    let linkStat;
+    try {
+        linkStat = await lstat(targetPath);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return 'missing';
+        throw e;
+    }
+    if (!linkStat.isSymbolicLink())
+        return 'conflict';
+    // 目标不存在（断链）
+    try {
+        await stat(targetPath);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return 'broken';
+        throw e;
+    }
+    try {
+        const logicalTarget = await logicalSymlinkTarget(targetPath);
+        if (logicalTarget === expectedSource)
+            return 'linked';
+        return 'conflict';
+    }
+    catch {
+        return 'broken';
+    }
+}
+/**
+ * 创建相对 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。
+ * 时间戳格式固定为 YYYYMMDDTHHmmssSSSZ（UTC）。
+ */
+async function moveToBackup(targetPath, storePath, resourceType, itemName, now) {
+    const ts = formatBackupTimestamp(now);
+    // 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;
+}
+/**
+ * 格式化备份时间戳为 YYYYMMDDTHHmmssSSSZ（UTC），不带分隔符。
+ */
+function formatBackupTimestamp(now) {
+    const iso = now.toISOString(); // YYYY-MM-DDTHH:mm:ss.sssZ
+    return iso.replace(/[-:]/g, '').replace('.', '');
+}
+/**
+ * 执行链接操作。
+ * linked 时也返回 record，供上层刷新 state（linkedAt/source 可能需要校正）。
+ */
+export async function linkItem(input) {
+    const { sourcePath, targetPath, resourceType, itemName, storePath, resolveConflict, now } = input;
+    const category = await classifyTarget(targetPath, sourcePath);
+    const timestamp = now ?? new Date();
+    const record = {
+        source: sourcePath,
+        target: targetPath,
+        linkedAt: timestamp.toISOString(),
+    };
+    if (category === 'linked') {
+        return { status: 'linked', record };
+    }
+    let policy;
+    if (category === 'conflict' || category === 'broken') {
+        // 仅真实冲突才解析策略：有 resolver 就问，否则回退静态 policy（默认 skip）
+        if (resolveConflict) {
+            policy = await resolveConflict();
+        }
+        else {
+            policy = input.policy ?? 'skip';
+        }
+        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 {
+                // 可能不存在或已被删除，忽略
+            }
+        }
+    }
+    else {
+        // missing：直接创建，无需策略
+        policy = 'skip';
+    }
+    // 创建新链接
+    await createRelativeSymlink(sourcePath, targetPath);
+    return {
+        status: category === 'missing' ? 'created' : policy === 'backup' ? 'backed-up' : 'overwritten',
+        record,
+    };
+}
+/**
+ * 安全删除 dak 管理的 symlink。
+ * 用 lstat 判存在（断链 symlink 也成功），用 readlink 逻辑解析比较：
+ * - target 不存在（lstat 抛 ENOENT）：missing
+ * - target 不是 symlink：conflict
+ * - 逻辑目标不在当前 store 内：conflict
+ * - 逻辑目标不等于 record.source：conflict
+ * 满足全部条件才 unlink。断链 symlink 也能被删除（source 已删，逻辑目标仍可解析）。
+ */
+export async function safeDeleteManagedLink(record, storePath) {
+    const { target, source } = record;
+    let linkStat;
+    try {
+        linkStat = await lstat(target);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return 'missing';
+        throw e;
+    }
+    if (!linkStat.isSymbolicLink())
+        return 'conflict';
+    let logicalTarget;
+    try {
+        logicalTarget = await logicalSymlinkTarget(target);
+    }
+    catch {
+        return 'conflict';
+    }
+    // 检查是否指向当前 store
+    if (!isPathInside(logicalTarget, storePath))
+        return 'conflict';
+    // 检查是否指向 record.source
+    if (logicalTarget !== source)
+        return 'conflict';
+    await unlink(target);
+    return 'deleted';
+}

package/dist/paths.js

@@ -0,0 +1,144 @@
+/** 路径工具函数 */
+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('\\')) {
+        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);
+}

package/dist/resources.js

@@ -0,0 +1,93 @@
+/** 资源扫描与格式化 */
+import { readdir, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { declaredResourceTypes } from './config.js';
+import { assertSafeItemName, isHiddenItem } from './paths.js';
+/**
+ * 资源类型在 list 输出中的显示标题。
+ * 默认类型固定标题；自定义类型首字母大写 + 冒号。
+ */
+function resourceLabel(type) {
+    const defaults = {
+        skills: 'Skills:',
+        hooks: 'Hooks:',
+        agents: 'Agents:',
+    };
+    if (defaults[type])
+        return defaults[type];
+    const cap = type.charAt(0).toUpperCase() + type.slice(1);
+    return `${cap}:`;
+}
+/**
+ * 确保 store 目录和声明的各资源类型目录存在。
+ */
+export async function ensureStoreLayout(storePath, config) {
+    await mkdir(storePath, { recursive: true });
+    for (const type of declaredResourceTypes(config)) {
+        await mkdir(join(storePath, type), { recursive: true });
+    }
+}
+/**
+ * 扫描 store 中声明的资源类型目录（一级子项）。
+ */
+export async function scanResources(storePath, config) {
+    const result = {};
+    for (const type of declaredResourceTypes(config)) {
+        result[type] = [];
+        const dir = join(storePath, type);
+        if (!existsSync(dir))
+            continue;
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            const items = [];
+            for (const entry of entries) {
+                const name = entry.name;
+                if (isHiddenItem(name))
+                    continue;
+                try {
+                    assertSafeItemName(name);
+                }
+                catch {
+                    continue;
+                }
+                const fullPath = join(dir, name);
+                let kind;
+                if (entry.isSymbolicLink())
+                    kind = 'symlink';
+                else if (entry.isDirectory())
+                    kind = 'directory';
+                else
+                    kind = 'file';
+                items.push({ name, kind, path: fullPath });
+            }
+            items.sort((a, b) => a.name.localeCompare(b.name));
+            result[type] = items;
+        }
+        catch {
+            // ignore unreadable dir
+        }
+    }
+    return result;
+}
+/**
+ * 格式化资源列表输出（供 `dak list` 使用）。
+ * 输出稳定，支持 snapshot 测试。
+ */
+export function formatResourceList(resources) {
+    const lines = [];
+    for (const type of Object.keys(resources)) {
+        lines.push(resourceLabel(type));
+        const items = resources[type];
+        if (items.length === 0) {
+            lines.push('  (empty)');
+        }
+        else {
+            for (const item of items) {
+                const kind = item.kind === 'directory' ? ' [dir]' : item.kind === 'symlink' ? ' [link]' : '';
+                lines.push(`  ${item.name}${kind}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}

package/dist/src/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/** dak CLI 入口 */
+import { runInit, runList, runLink, runStatus, runUpdate, runUnlink } from './commands.js';
+/** 解析命令行参数（不引入额外依赖） */
+export function parseArgv(argv) {
+    const result = { command: 'list' };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--store' && argv[i + 1]) {
+            result.store = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (arg === '--on-conflict' && argv[i + 1]) {
+            const val = argv[i + 1];
+            if (!['skip', 'backup', 'overwrite'].includes(val)) {
+                throw new Error('Invalid conflict policy');
+            }
+            result.onConflict = val;
+            i++;
+            continue;
+        }
+        // 第一个非 flag 参数为命令或 target
+        if (!arg.startsWith('--')) {
+            const cmd = arg;
+            if (['init', 'list', 'link', 'status', 'update', 'unlink'].includes(cmd)) {
+                result.command = cmd;
+                // link/unlink 后跟 target
+                if (cmd === 'link' || cmd === 'unlink') {
+                    const next = argv[i + 1];
+                    if (!next || next.startsWith('--')) {
+                        throw new Error(`${cmd} target is required`);
+                    }
+                    result.target = next;
+                    i++;
+                }
+            }
+            else {
+                throw new Error(`Unknown command: ${arg}`);
+            }
+        }
+    }
+    // link/unlink 必须有 target
+    if ((result.command === 'link' || result.command === 'unlink') && !result.target) {
+        throw new Error(`${result.command} target is required`);
+    }
+    return result;
+}
+/** 主入口 */
+export async function main(args = process.argv.slice(2)) {
+    const homeDir = process.env.HOME ?? '';
+    const interactive = process.stdin.isTTY && process.stdout.isTTY;
+    try {
+        const parsed = parseArgv(args);
+        const opts = { store: parsed.store, homeDir };
+        // 冲突策略
+        if (parsed.onConflict) {
+            opts.conflictPolicy = parsed.onConflict;
+        }
+        else if (interactive) {
+            opts.interactive = true;
+            opts.chooseConflict = async (_target, _resource, _item) => {
+                // 简单实现：默认 skip
+                return 'skip';
+            };
+        }
+        switch (parsed.command) {
+            case 'init':
+                console.log(await runInit(opts));
+                break;
+            case 'list':
+                console.log(await runList(opts));
+                break;
+            case 'link':
+                console.log(await runLink(parsed.target, opts));
+                break;
+            case 'status':
+                console.log(await runStatus(opts));
+                break;
+            case 'update':
+                console.log(await runUpdate(opts));
+                break;
+            case 'unlink':
+                console.log(await runUnlink(parsed.target, opts));
+                break;
+        }
+        return 0;
+    }
+    catch (e) {
+        console.error(`Error: ${e.message}`);
+        return 1;
+    }
+}
+// 直接运行时执行 main
+if (process.argv[1] === import.meta.url) {
+    main().then(code => process.exit(code));
+}