@myagentroam/node 0.1.6 → 0.1.8

package/dist/service/skill-install-service.js

@@ -0,0 +1,504 @@
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { lstat, mkdir, readFile, readdir, readlink, realpath, rename, rm, symlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { skillInstallMetadataSchema } from '@myagentroam/protocol';
+export class SkillInstallService {
+    async recoverNodeHome(home) {
+        const agentsRoot = path.join(home, '.agents', 'skills');
+        const claudeRoot = path.join(home, '.claude', 'skills');
+        await assertExistingContainedDirectory(home, agentsRoot);
+        const roots = [agentsRoot];
+        if (await exists(claudeRoot)) {
+            const stat = await lstat(claudeRoot);
+            if (stat.isSymbolicLink()) {
+                if (!(await exists(agentsRoot)) ||
+                    (await realpath(claudeRoot)) !== (await realpath(agentsRoot)))
+                    throw new Error('NODE_SKILL_LINK_UNAVAILABLE');
+            }
+            else {
+                await assertContainedDirectory(home, claudeRoot);
+                roots.push(claudeRoot);
+            }
+        }
+        await recoverTransactions(roots);
+    }
+    async recoverWorkspace(workspace) {
+        const roots = [
+            path.join(workspace, '.agents', 'skills'),
+            path.join(workspace, '.claude', 'skills')
+        ];
+        for (const root of roots)
+            await assertExistingContainedDirectory(workspace, root);
+        await recoverTransactions(roots);
+    }
+    async installNodeHome(home, name, bundle, metadata) {
+        assertName(name);
+        skillInstallMetadataSchema.parse(metadata);
+        const agentsRoot = path.join(home, '.agents', 'skills');
+        await mkdir(agentsRoot, { recursive: true });
+        await assertContainedDirectory(home, agentsRoot);
+        const claudeRoot = path.join(home, '.claude', 'skills');
+        const mode = await ensureClaudeRoot(agentsRoot, claudeRoot);
+        if (mode === 'MANAGED_COPY')
+            await assertContainedDirectory(home, claudeRoot);
+        await replaceDirectory(agentsRoot, name, bundle, metadata);
+        if (mode === 'MANAGED_COPY')
+            await replaceDirectory(claudeRoot, name, bundle, metadata);
+    }
+    async installWorkspace(workspace, name, bundle, metadata, options = {}) {
+        assertName(name);
+        skillInstallMetadataSchema.parse(metadata);
+        if (!options.confirmTracked && (await workspaceSkillTracked(workspace, name)))
+            throw new Error('WORKSPACE_SKILL_TRACKED_CONFIRM_REQUIRED');
+        const agentsRoot = path.join(workspace, '.agents', 'skills');
+        const claudeRoot = path.join(workspace, '.claude', 'skills');
+        await mkdir(agentsRoot, { recursive: true });
+        await mkdir(claudeRoot, { recursive: true });
+        await assertContainedDirectory(workspace, agentsRoot);
+        await assertContainedDirectory(workspace, claudeRoot);
+        await replacePair(agentsRoot, claudeRoot, name, bundle, metadata, () => updateGitExclude(workspace, name, true), () => updateGitExclude(workspace, name, false));
+    }
+    async removeWorkspace(workspace, name) {
+        assertName(name);
+        const agentsRoot = path.join(workspace, '.agents', 'skills');
+        const claudeRoot = path.join(workspace, '.claude', 'skills');
+        await assertExistingContainedDirectory(workspace, agentsRoot);
+        await assertExistingContainedDirectory(workspace, claudeRoot);
+        await removePair(agentsRoot, claudeRoot, name, () => updateGitExclude(workspace, name, false), () => updateGitExclude(workspace, name, true));
+    }
+    async removeNodeHome(home, name) {
+        assertName(name);
+        const agentsRoot = path.join(home, '.agents', 'skills');
+        const claudeRoot = path.join(home, '.claude', 'skills');
+        const mode = await ensureClaudeRoot(agentsRoot, claudeRoot);
+        if (mode === 'MANAGED_COPY')
+            await assertContainedDirectory(home, claudeRoot);
+        if (mode === 'MANAGED_COPY')
+            await removePair(agentsRoot, claudeRoot, name);
+        else
+            await removeSingle(agentsRoot, name);
+    }
+    async repairWorkspaceGitExclude(workspace) {
+        const root = path.join(workspace, '.agents', 'skills');
+        const names = new Set();
+        try {
+            for (const entry of await readdir(root, { withFileTypes: true })) {
+                if (!entry.isDirectory() || entry.isSymbolicLink())
+                    continue;
+                try {
+                    assertName(entry.name);
+                    names.add(entry.name);
+                }
+                catch {
+                    // Invalid directory names remain visible to inspection but are never written as patterns.
+                }
+            }
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        await rewriteGitExclude(workspace, names);
+    }
+}
+export async function workspaceSkillTracked(workspace, name) {
+    assertName(name);
+    if (!(await exists(path.join(workspace, '.git'))))
+        return false;
+    try {
+        const result = await promisify(execFile)('git', ['-C', workspace, 'ls-files', '--', `.agents/skills/${name}`, `.claude/skills/${name}`], { timeout: 5_000, windowsHide: true });
+        return result.stdout.trim() !== '';
+    }
+    catch {
+        throw new Error('WORKSPACE_SKILL_GIT_EXCLUDE_FAILED');
+    }
+}
+async function replacePair(firstRoot, secondRoot, name, bundle, metadata, beforeCommit, rollbackSideEffect) {
+    const transactionId = randomUUID();
+    const first = await prepare(firstRoot, name, bundle, metadata);
+    let second;
+    let sideEffectApplied = false;
+    try {
+        second = await prepare(secondRoot, name, bundle, metadata);
+        await writeTransaction([firstRoot, secondRoot], transactionId, 'PREPARED', [first, second]);
+        await commitPrepared(first);
+        await commitPrepared(second);
+        await beforeCommit?.();
+        sideEffectApplied = beforeCommit !== undefined;
+        await writeTransaction([firstRoot, secondRoot], transactionId, 'COMMITTED', [first, second]);
+    }
+    catch (error) {
+        if (sideEffectApplied)
+            await rollbackSideEffect?.();
+        if (second !== undefined)
+            await rollbackPrepared(second);
+        await rollbackPrepared(first);
+        await removeTransaction([firstRoot, secondRoot], transactionId);
+        throw error;
+    }
+    try {
+        await cleanupPrepared(first);
+        await cleanupPrepared(second);
+        await removeTransaction([firstRoot, secondRoot], transactionId);
+    }
+    catch {
+        // COMMITTED journal remains authoritative and the next inspect/install finishes cleanup.
+    }
+}
+async function replaceDirectory(root, name, bundle, metadata) {
+    const transactionId = randomUUID();
+    const prepared = await prepare(root, name, bundle, metadata);
+    try {
+        await writeTransaction([root], transactionId, 'PREPARED', [prepared]);
+        await commitPrepared(prepared);
+        await writeTransaction([root], transactionId, 'COMMITTED', [prepared]);
+    }
+    catch (error) {
+        await rollbackPrepared(prepared);
+        await removeTransaction([root], transactionId);
+        throw error;
+    }
+    try {
+        await cleanupPrepared(prepared);
+        await removeTransaction([root], transactionId);
+    }
+    catch {
+        // COMMITTED journal remains authoritative and the next inspect/install finishes cleanup.
+    }
+}
+async function writeTransaction(roots, transactionId, state, items) {
+    const record = {
+        schemaVersion: 1,
+        transactionId,
+        state,
+        roots,
+        items: items.map(({ target, staging, backup, hadTarget }) => ({
+            target,
+            staging,
+            backup,
+            hadTarget
+        }))
+    };
+    for (const root of roots) {
+        await mkdir(root, { recursive: true });
+        const destination = transactionPath(root, transactionId);
+        const staging = `${destination}.tmp`;
+        await writeFile(staging, JSON.stringify(record), { flag: 'w' });
+        await rename(staging, destination);
+    }
+}
+async function removeTransaction(roots, transactionId) {
+    await Promise.all(roots.map((root) => rm(transactionPath(root, transactionId), { force: true })));
+}
+async function recoverTransactions(roots) {
+    const normalizedRoots = roots.map((root) => path.resolve(root));
+    const records = new Map();
+    for (const root of normalizedRoots) {
+        let entries;
+        try {
+            entries = await readdir(root);
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            throw error;
+        }
+        for (const entry of entries.filter((name) => /^\.mar-transaction-[0-9a-f-]+\.json$/u.test(name))) {
+            let record;
+            try {
+                record = JSON.parse(await readFile(path.join(root, entry), 'utf8'));
+                validateTransaction(record, normalizedRoots);
+            }
+            catch {
+                throw new Error('SKILL_INSTALL_RECOVERY_REQUIRED');
+            }
+            records.set(record.transactionId, record);
+        }
+    }
+    for (const record of records.values()) {
+        if (record.state === 'COMMITTED') {
+            for (const item of record.items) {
+                await rm(item.backup, { recursive: true, force: true });
+                await rm(item.staging, { recursive: true, force: true });
+            }
+        }
+        else {
+            for (const item of [...record.items].reverse())
+                await recoverPrepared(item);
+        }
+        await removeTransaction(record.roots, record.transactionId);
+    }
+}
+async function recoverPrepared(item) {
+    if (await exists(item.backup)) {
+        await rm(item.target, { recursive: true, force: true });
+        await rename(item.backup, item.target);
+    }
+    else if (!item.hadTarget && (await exists(item.target)) && !(await exists(item.staging))) {
+        await rm(item.target, { recursive: true, force: true });
+    }
+    await rm(item.staging, { recursive: true, force: true });
+}
+function validateTransaction(record, roots) {
+    if (record.schemaVersion !== 1 ||
+        !/^[0-9a-f-]{36}$/u.test(record.transactionId) ||
+        !['PREPARED', 'COMMITTED'].includes(record.state) ||
+        !Array.isArray(record.roots) ||
+        record.roots.some((root) => !roots.includes(path.resolve(root))) ||
+        !Array.isArray(record.items) ||
+        record.items.length < 1 ||
+        record.items.length > 2)
+        throw new Error('SKILL_INSTALL_RECOVERY_REQUIRED');
+    for (const item of record.items) {
+        const root = path.dirname(item.target);
+        if (!roots.includes(path.resolve(root)) ||
+            path.dirname(item.staging) !== root ||
+            path.dirname(item.backup) !== root ||
+            !path.basename(item.staging).startsWith('.mar-staging-') ||
+            !path.basename(item.backup).startsWith('.mar-backup-'))
+            throw new Error('SKILL_INSTALL_RECOVERY_REQUIRED');
+    }
+}
+function transactionPath(root, transactionId) {
+    return path.join(root, `.mar-transaction-${transactionId}.json`);
+}
+async function prepare(root, name, bundle, metadata) {
+    await mkdir(root, { recursive: true });
+    const caseCollision = (await readdir(root)).find((entry) => entry.toLowerCase() === name && entry !== name);
+    if (caseCollision !== undefined)
+        throw new Error('SKILL_NAME_CONFLICT');
+    const target = path.join(root, name);
+    const staging = path.join(root, `.mar-staging-${randomUUID()}`);
+    const backup = path.join(root, `.mar-backup-${randomUUID()}`);
+    const hadTarget = await exists(target);
+    if (hadTarget) {
+        const targetStat = await lstat(target);
+        if (!targetStat.isDirectory() && !targetStat.isSymbolicLink())
+            throw new Error('SKILL_INSTALL_INVALID_LINK');
+    }
+    await mkdir(staging, { recursive: false });
+    try {
+        if (bundle.schemaVersion !== 1 || bundle.files.length === 0 || bundle.files.length > 1_000)
+            throw new Error('SKILL_CONTENT_INVALID');
+        const paths = new Set();
+        for (const file of bundle.files) {
+            assertRelative(file.path);
+            if (paths.has(file.path))
+                throw new Error('SKILL_CONTENT_INVALID');
+            paths.add(file.path);
+            const destination = path.join(staging, ...file.path.split('/'));
+            await mkdir(path.dirname(destination), { recursive: true });
+            await writeFile(destination, Buffer.from(file.contentBase64, 'base64'), { flag: 'wx' });
+        }
+        await writeFile(path.join(staging, '.mar-skill-install.json'), JSON.stringify(metadata), {
+            flag: 'wx'
+        });
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+    return { target, staging, backup, hadTarget, committed: false };
+}
+async function assertContainedDirectory(container, directory) {
+    const [containerReal, directoryReal] = await Promise.all([
+        realpath(container),
+        realpath(directory)
+    ]);
+    const relative = path.relative(containerReal, directoryReal);
+    if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative))
+        throw new Error('SKILL_PATH_UNSAFE');
+}
+async function assertExistingContainedDirectory(container, directory) {
+    if (await exists(directory))
+        await assertContainedDirectory(container, directory);
+}
+async function removeSingle(root, name) {
+    const target = path.join(root, name);
+    if (!(await exists(target)))
+        return;
+    const stat = await lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('SKILL_INSTALL_INVALID_LINK');
+    const backup = path.join(root, `.mar-delete-${randomUUID()}`);
+    await rename(target, backup);
+    await rm(backup, { recursive: true, force: true });
+}
+async function commitPrepared(item) {
+    if (item.hadTarget)
+        await rename(item.target, item.backup);
+    await rename(item.staging, item.target);
+    item.committed = true;
+}
+async function rollbackPrepared(item) {
+    if (item.committed)
+        await rm(item.target, { recursive: true, force: true });
+    if (await exists(item.backup))
+        await rename(item.backup, item.target);
+    await rm(item.staging, { recursive: true, force: true });
+}
+async function cleanupPrepared(item) {
+    await rm(item.backup, { recursive: true, force: true });
+}
+async function removePair(firstRoot, secondRoot, name, beforeCommit, rollbackSideEffect) {
+    const first = path.join(firstRoot, name);
+    const second = path.join(secondRoot, name);
+    for (const target of [first, second]) {
+        if (!(await exists(target)))
+            continue;
+        const stat = await lstat(target);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('SKILL_INSTALL_INVALID_LINK');
+    }
+    const firstBackup = `${first}.mar-delete-${randomUUID()}`;
+    const secondBackup = `${second}.mar-delete-${randomUUID()}`;
+    let sideEffectApplied = false;
+    try {
+        if (await exists(first))
+            await rename(first, firstBackup);
+        if (await exists(second))
+            await rename(second, secondBackup);
+        await beforeCommit?.();
+        sideEffectApplied = beforeCommit !== undefined;
+        await rm(firstBackup, { recursive: true, force: true });
+        await rm(secondBackup, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (sideEffectApplied)
+            await rollbackSideEffect?.();
+        if (await exists(firstBackup))
+            await rename(firstBackup, first);
+        if (await exists(secondBackup))
+            await rename(secondBackup, second);
+        throw error;
+    }
+}
+async function ensureClaudeRoot(agentsRoot, claudeRoot) {
+    try {
+        const stat = await lstat(claudeRoot);
+        if (stat.isSymbolicLink()) {
+            const linked = await realpath(path.resolve(path.dirname(claudeRoot), await readlink(claudeRoot)));
+            const agents = await realpath(agentsRoot);
+            if (linked !== agents)
+                throw new Error('NODE_SKILL_LINK_UNAVAILABLE');
+            return 'LINK';
+        }
+        if (stat.isDirectory())
+            return 'MANAGED_COPY';
+        throw new Error('NODE_SKILL_LINK_UNAVAILABLE');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        await mkdir(path.dirname(claudeRoot), { recursive: true });
+        try {
+            await symlink(agentsRoot, claudeRoot, process.platform === 'win32' ? 'junction' : 'dir');
+            return 'LINK';
+        }
+        catch (linkError) {
+            if (process.platform !== 'win32')
+                throw linkError;
+            await mkdir(claudeRoot, { recursive: true });
+            return 'MANAGED_COPY';
+        }
+    }
+}
+async function updateGitExclude(workspace, name, add) {
+    await mutateGitExclude(workspace, (entries) => {
+        for (const root of ['.agents', '.claude']) {
+            const line = `/${root}/skills/${name}/`;
+            if (add)
+                entries.add(line);
+            else
+                entries.delete(line);
+        }
+    });
+}
+async function rewriteGitExclude(workspace, names) {
+    await mutateGitExclude(workspace, (entries) => {
+        entries.clear();
+        for (const name of names)
+            for (const root of ['.agents', '.claude'])
+                entries.add(`/${root}/skills/${name}/`);
+    });
+}
+async function mutateGitExclude(workspace, mutate) {
+    const git = path.join(workspace, '.git');
+    if (!(await exists(git)))
+        return;
+    let exclude;
+    try {
+        const result = await promisify(execFile)('git', ['-C', workspace, 'rev-parse', '--git-path', 'info/exclude', '--git-common-dir'], { timeout: 5_000, windowsHide: true });
+        const [excludeOutput, commonOutput] = result.stdout.trim().split(/\r?\n/u);
+        if (!excludeOutput || !commonOutput)
+            throw new Error('WORKSPACE_SKILL_GIT_EXCLUDE_FAILED');
+        exclude = path.resolve(workspace, excludeOutput);
+        const common = path.resolve(workspace, commonOutput);
+        const relative = path.relative(common, exclude);
+        if (relative.startsWith('..') || path.isAbsolute(relative))
+            throw new Error('WORKSPACE_SKILL_GIT_EXCLUDE_FAILED');
+    }
+    catch {
+        throw new Error('WORKSPACE_SKILL_GIT_EXCLUDE_FAILED');
+    }
+    await mkdir(path.dirname(exclude), { recursive: true });
+    const begin = '# BEGIN MyAgentRoam Skills';
+    const end = '# END MyAgentRoam Skills';
+    let content = '';
+    try {
+        const excludeStat = await lstat(exclude);
+        if (!excludeStat.isFile() || excludeStat.isSymbolicLink())
+            throw new Error('WORKSPACE_SKILL_GIT_EXCLUDE_FAILED');
+        content = await readFile(exclude, 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    const pattern = new RegExp(`${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}\\n?`, 'u');
+    const existing = pattern.exec(content)?.[0] ?? '';
+    const entries = new Set(existing.split(/\r?\n/u).filter((line) => line.startsWith('/.')));
+    mutate(entries);
+    const block = entries.size === 0 ? '' : `${begin}\n${[...entries].sort().join('\n')}\n${end}\n`;
+    const next = content.replace(pattern, '').replace(/\s*$/u, '\n') + block;
+    const staging = path.join(path.dirname(exclude), `.mar-git-exclude-${randomUUID()}.tmp`);
+    try {
+        await writeFile(staging, next, { encoding: 'utf8', flag: 'wx' });
+        await rename(staging, exclude);
+    }
+    catch (error) {
+        await rm(staging, { force: true });
+        throw error;
+    }
+}
+function assertName(name) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name) ||
+        /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/u.test(name))
+        throw new Error('SKILL_NAME_CONFLICT');
+}
+function assertRelative(value) {
+    if (value === '' ||
+        value.startsWith('/') ||
+        value.includes('\\') ||
+        value.split('/').some((part) => part === '' || part === '.' || part === '..'))
+        throw new Error('SKILL_PATH_UNSAFE');
+}
+async function exists(value) {
+    try {
+        await lstat(value);
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+function isMissing(error) {
+    return (error instanceof Error && 'code' in error && error.code === 'ENOENT');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}

package/dist/service/skill-node-operation-service.d.ts

@@ -0,0 +1,44 @@
+import type { NodeConfig } from '../config.js';
+import type { NodeDatabase } from '../database.js';
+export declare class SkillNodeOperationService {
+    private readonly database;
+    private readonly config;
+    private readonly directories;
+    private readonly installer;
+    private readonly activeTargets;
+    private readonly jobs;
+    constructor(database: () => NodeDatabase, config: () => NodeConfig);
+    operations(): {
+        'node.skills.inspect': () => Promise<import("./skill-directory-service.js").LocalSkillTargetInspection>;
+        'node.skills.install': (data: unknown) => Promise<{
+            accepted: boolean;
+            installJobId: `${string}-${string}-${string}-${string}-${string}`;
+        }>;
+        'node.skills.remove': (data: unknown) => Promise<{
+            removed: boolean;
+        }>;
+        'workspace.skills.inspect': (data: unknown) => Promise<import("./skill-directory-service.js").LocalSkillTargetInspection>;
+        'workspace.skills.install': (data: unknown) => Promise<{
+            accepted: boolean;
+            installJobId: `${string}-${string}-${string}-${string}-${string}`;
+        }>;
+        'workspace.skills.remove': (data: unknown) => Promise<{
+            removed: boolean;
+        }>;
+        'workspace.skills.git-exclude-repair': (data: unknown) => Promise<{
+            repaired: boolean;
+        }>;
+        'skill.install.job.get': (data: unknown) => {
+            errorCode?: string;
+            installJobId: string;
+            status: "RUNNING" | "SUCCEEDED" | "FAILED";
+        };
+    };
+    private install;
+    private job;
+    private cleanupJobs;
+    private performInstall;
+    private remove;
+    private workspacePath;
+    private download;
+}