feat(mosaic): add secure skill registration CLI (#826)
This commit was merged in pull request #826.
This commit is contained in:
421
packages/mosaic/src/commands/skill.spec.ts
Normal file
421
packages/mosaic/src/commands/skill.spec.ts
Normal file
@@ -0,0 +1,421 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
import { Command } from 'commander';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import {
|
||||
existsSync,
|
||||
lstatSync,
|
||||
mkdirSync,
|
||||
mkdtempSync,
|
||||
readlinkSync,
|
||||
rmSync,
|
||||
symlinkSync,
|
||||
writeFileSync,
|
||||
} from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import {
|
||||
listSkills,
|
||||
registerSkill,
|
||||
registerSkillCommand,
|
||||
syncClaudeSkills,
|
||||
unregisterSkill,
|
||||
type SkillPaths,
|
||||
} from './skill.js';
|
||||
|
||||
const LEGACY_SYNC_SCRIPT = fileURLToPath(
|
||||
new URL('../../framework/tools/_scripts/mosaic-sync-skills', import.meta.url),
|
||||
);
|
||||
|
||||
describe('Claude skill bridge', () => {
|
||||
let root: string;
|
||||
let paths: SkillPaths;
|
||||
|
||||
beforeEach(() => {
|
||||
root = mkdtempSync(join(tmpdir(), 'mosaic-skill-cli-'));
|
||||
paths = {
|
||||
mosaicSkillsDir: join(root, '.config', 'mosaic', 'skills'),
|
||||
claudeSkillsDir: join(root, '.claude', 'skills'),
|
||||
};
|
||||
mkdirSync(paths.mosaicSkillsDir, { recursive: true });
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
function createSkill(name: string): string {
|
||||
const skillDir = join(paths.mosaicSkillsDir, name);
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
writeFileSync(join(skillDir, 'SKILL.md'), `# ${name}\n`);
|
||||
return skillDir;
|
||||
}
|
||||
|
||||
function expectCorrectLink(name: string): void {
|
||||
const linkPath = join(paths.claudeSkillsDir, name);
|
||||
expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
|
||||
expect(readlinkSync(linkPath)).toBe(join(paths.mosaicSkillsDir, name));
|
||||
}
|
||||
|
||||
describe('name validation', () => {
|
||||
const invalidNames = [
|
||||
'../../etc',
|
||||
'/abs/path',
|
||||
'a/b',
|
||||
String.raw`a\b`,
|
||||
'-rf',
|
||||
'..',
|
||||
'safe.',
|
||||
'space name',
|
||||
'line\nbreak',
|
||||
'escape\u001B[31m',
|
||||
];
|
||||
|
||||
for (const name of invalidNames) {
|
||||
it(`rejects ${JSON.stringify(name)} before register can escape its roots`, () => {
|
||||
expect(() => registerSkill(name, paths)).toThrow(/invalid skill name/i);
|
||||
expect(existsSync(paths.claudeSkillsDir)).toBe(false);
|
||||
});
|
||||
|
||||
it(`rejects ${JSON.stringify(name)} before unregister can escape its roots`, () => {
|
||||
expect(() => unregisterSkill(name, paths)).toThrow(/invalid skill name/i);
|
||||
expect(existsSync(paths.claudeSkillsDir)).toBe(false);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
describe('CLI validation errors', () => {
|
||||
let previousExitCode: number | string | null | undefined;
|
||||
|
||||
beforeEach(() => {
|
||||
previousExitCode = process.exitCode;
|
||||
process.exitCode = undefined;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
process.exitCode = previousExitCode;
|
||||
});
|
||||
|
||||
it.each(['register', 'unregister'])(
|
||||
'reports invalid %s names on stderr and sets a nonzero exit status',
|
||||
async (subcommand) => {
|
||||
const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
|
||||
const program = new Command().exitOverride();
|
||||
registerSkillCommand(program, paths);
|
||||
|
||||
await program.parseAsync(['node', 'mosaic', 'skill', subcommand, '../../etc']);
|
||||
|
||||
expect(error).toHaveBeenCalledWith(expect.stringMatching(/invalid skill name/i));
|
||||
expect(process.exitCode).toBe(1);
|
||||
expect(existsSync(paths.claudeSkillsDir)).toBe(false);
|
||||
error.mockRestore();
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
describe('CLI status output', () => {
|
||||
let previousExitCode: number | string | null | undefined;
|
||||
|
||||
beforeEach(() => {
|
||||
previousExitCode = process.exitCode;
|
||||
process.exitCode = undefined;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
process.exitCode = previousExitCode;
|
||||
});
|
||||
|
||||
async function run(...args: string[]): Promise<void> {
|
||||
const program = new Command().exitOverride();
|
||||
registerSkillCommand(program, paths);
|
||||
await program.parseAsync(['node', 'mosaic', 'skill', ...args]);
|
||||
}
|
||||
|
||||
it('reports register repair/idempotency and unregister idempotency statuses', async () => {
|
||||
const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
|
||||
createSkill('status-skill');
|
||||
|
||||
await run('register', 'status-skill');
|
||||
await run('register', 'status-skill');
|
||||
rmSync(join(paths.claudeSkillsDir, 'status-skill'));
|
||||
symlinkSync(
|
||||
join(paths.mosaicSkillsDir, 'retired'),
|
||||
join(paths.claudeSkillsDir, 'status-skill'),
|
||||
);
|
||||
await run('register', 'status-skill');
|
||||
await run('unregister', 'status-skill');
|
||||
await run('unregister', 'status-skill');
|
||||
|
||||
expect(log.mock.calls.flat()).toEqual([
|
||||
'status-skill: registered',
|
||||
'status-skill: already registered',
|
||||
'status-skill: repaired dangling registration',
|
||||
'status-skill: unregistered',
|
||||
'status-skill: already unregistered',
|
||||
]);
|
||||
log.mockRestore();
|
||||
});
|
||||
|
||||
it('reports empty and populated skill lists', async () => {
|
||||
const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
|
||||
|
||||
await run('list');
|
||||
createSkill('listed');
|
||||
await run('list');
|
||||
|
||||
expect(log).toHaveBeenCalledWith('No Mosaic or Claude Code skills found.');
|
||||
expect(log).toHaveBeenCalledWith(expect.stringMatching(/^unregistered\s+listed$/));
|
||||
log.mockRestore();
|
||||
});
|
||||
});
|
||||
|
||||
describe('registerSkill', () => {
|
||||
it('creates the exact canonical symlink and is idempotent', () => {
|
||||
createSkill('new-skill');
|
||||
|
||||
expect(registerSkill('new-skill', paths).status).toBe('registered');
|
||||
expectCorrectLink('new-skill');
|
||||
|
||||
expect(registerSkill('new-skill', paths).status).toBe('already-registered');
|
||||
expectCorrectLink('new-skill');
|
||||
});
|
||||
|
||||
it('repairs a dangling Mosaic-owned symlink', () => {
|
||||
createSkill('new-skill');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
symlinkSync(
|
||||
join(paths.mosaicSkillsDir, 'retired-skill'),
|
||||
join(paths.claudeSkillsDir, 'new-skill'),
|
||||
);
|
||||
|
||||
expect(registerSkill('new-skill', paths).status).toBe('repaired');
|
||||
expectCorrectLink('new-skill');
|
||||
});
|
||||
|
||||
it.each(['file', 'directory', 'symlink'] as const)(
|
||||
'refuses to clobber a foreign %s at the target',
|
||||
(kind) => {
|
||||
createSkill('protected');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
const target = join(paths.claudeSkillsDir, 'protected');
|
||||
const foreign = join(root, 'foreign');
|
||||
|
||||
if (kind === 'file') writeFileSync(target, 'keep me\n');
|
||||
if (kind === 'directory') mkdirSync(target);
|
||||
if (kind === 'symlink') {
|
||||
writeFileSync(foreign, 'keep me\n');
|
||||
symlinkSync(foreign, target);
|
||||
}
|
||||
|
||||
expect(() => registerSkill('protected', paths)).toThrow(/foreign|refus/i);
|
||||
if (kind === 'file') expect(lstatSync(target).isFile()).toBe(true);
|
||||
if (kind === 'directory') expect(lstatSync(target).isDirectory()).toBe(true);
|
||||
if (kind === 'symlink') expect(readlinkSync(target)).toBe(foreign);
|
||||
},
|
||||
);
|
||||
|
||||
it('refuses a symlinked Claude skills ancestor instead of writing outside the bridge root', () => {
|
||||
createSkill('protected');
|
||||
const externalClaude = join(root, 'external-claude');
|
||||
mkdirSync(externalClaude);
|
||||
symlinkSync(externalClaude, join(root, '.claude'));
|
||||
|
||||
expect(() => registerSkill('protected', paths)).toThrow(
|
||||
/symlink.*ancestor|ancestor.*symlink/i,
|
||||
);
|
||||
expect(existsSync(join(externalClaude, 'skills', 'protected'))).toBe(false);
|
||||
});
|
||||
|
||||
it('refuses a symlinked canonical skills root instead of registering an external source', () => {
|
||||
rmSync(paths.mosaicSkillsDir, { recursive: true });
|
||||
const externalSkills = join(root, 'external-skills');
|
||||
mkdirSync(join(externalSkills, 'protected'), { recursive: true });
|
||||
symlinkSync(externalSkills, paths.mosaicSkillsDir);
|
||||
|
||||
expect(() => registerSkill('protected', paths)).toThrow(
|
||||
/symlink.*ancestor|ancestor.*symlink/i,
|
||||
);
|
||||
expect(existsSync(paths.claudeSkillsDir)).toBe(false);
|
||||
});
|
||||
|
||||
it('refuses a dangling foreign symlink rather than treating it as repairable', () => {
|
||||
createSkill('protected');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
const foreignMissing = join(root, 'foreign-missing');
|
||||
const target = join(paths.claudeSkillsDir, 'protected');
|
||||
symlinkSync(foreignMissing, target);
|
||||
|
||||
expect(() => registerSkill('protected', paths)).toThrow(/foreign|refus/i);
|
||||
expect(readlinkSync(target)).toBe(foreignMissing);
|
||||
});
|
||||
});
|
||||
|
||||
describe('unregisterSkill', () => {
|
||||
it('removes a Mosaic-owned symlink and is idempotent when absent', () => {
|
||||
createSkill('removable');
|
||||
registerSkill('removable', paths);
|
||||
|
||||
expect(unregisterSkill('removable', paths).status).toBe('unregistered');
|
||||
expect(existsSync(join(paths.claudeSkillsDir, 'removable'))).toBe(false);
|
||||
|
||||
expect(unregisterSkill('removable', paths).status).toBe('already-unregistered');
|
||||
});
|
||||
|
||||
it('refuses to remove a misdirected Mosaic-root symlink', () => {
|
||||
createSkill('other');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
const requested = join(paths.claudeSkillsDir, 'requested');
|
||||
symlinkSync(join(paths.mosaicSkillsDir, 'other'), requested);
|
||||
|
||||
expect(() => unregisterSkill('requested', paths)).toThrow(/misdirected/i);
|
||||
expect(readlinkSync(requested)).toBe(join(paths.mosaicSkillsDir, 'other'));
|
||||
});
|
||||
|
||||
it.each(['file', 'directory', 'symlink'] as const)('refuses to remove a foreign %s', (kind) => {
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
const target = join(paths.claudeSkillsDir, 'protected');
|
||||
const foreign = join(root, 'foreign');
|
||||
|
||||
if (kind === 'file') writeFileSync(target, 'keep me\n');
|
||||
if (kind === 'directory') mkdirSync(target);
|
||||
if (kind === 'symlink') {
|
||||
writeFileSync(foreign, 'keep me\n');
|
||||
symlinkSync(foreign, target);
|
||||
}
|
||||
|
||||
expect(() => unregisterSkill('protected', paths)).toThrow(/foreign|refus/i);
|
||||
expect(lstatSync(target)).toBeDefined();
|
||||
if (kind === 'symlink') expect(readlinkSync(target)).toBe(foreign);
|
||||
});
|
||||
});
|
||||
|
||||
describe('listSkills', () => {
|
||||
it('flags registered, unregistered, Mosaic-owned dangling, and foreign entries', () => {
|
||||
createSkill('registered');
|
||||
createSkill('unregistered');
|
||||
registerSkill('registered', paths);
|
||||
symlinkSync(join(paths.mosaicSkillsDir, 'retired'), join(paths.claudeSkillsDir, 'dangling'));
|
||||
writeFileSync(join(paths.claudeSkillsDir, 'foreign-file'), 'keep me\n');
|
||||
symlinkSync(join(root, 'missing-foreign'), join(paths.claudeSkillsDir, 'foreign-link'));
|
||||
|
||||
expect(listSkills(paths)).toEqual([
|
||||
expect.objectContaining({ name: 'dangling', status: 'dangling' }),
|
||||
expect.objectContaining({ name: 'foreign-file', status: 'foreign' }),
|
||||
expect.objectContaining({ name: 'foreign-link', status: 'foreign-dangling' }),
|
||||
expect.objectContaining({ name: 'registered', status: 'registered' }),
|
||||
expect.objectContaining({ name: 'unregistered', status: 'unregistered' }),
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('install linker compatibility', () => {
|
||||
it('preserves foreign-name links into Mosaic home but outside canonical skills', () => {
|
||||
createSkill('missing');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
const mosaicHome = join(root, '.config', 'mosaic');
|
||||
const liveForeignTarget = join(mosaicHome, 'foreign-non-skill-target');
|
||||
mkdirSync(liveForeignTarget);
|
||||
const liveForeignLink = join(paths.claudeSkillsDir, 'foreign-tool');
|
||||
const danglingForeignLink = join(paths.claudeSkillsDir, 'unresolvable-foreign');
|
||||
symlinkSync(liveForeignTarget, liveForeignLink);
|
||||
symlinkSync(join(mosaicHome, 'foreign-missing'), danglingForeignLink);
|
||||
|
||||
const result = spawnSync('bash', [LEGACY_SYNC_SCRIPT, '--link-only'], {
|
||||
encoding: 'utf8',
|
||||
env: { ...process.env, HOME: root, MOSAIC_HOME: mosaicHome },
|
||||
});
|
||||
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
expect(readlinkSync(liveForeignLink)).toBe(liveForeignTarget);
|
||||
expect(readlinkSync(danglingForeignLink)).toBe(join(mosaicHome, 'foreign-missing'));
|
||||
expect(readlinkSync(join(paths.claudeSkillsDir, 'missing'))).toBe(
|
||||
join(paths.mosaicSkillsDir, 'missing'),
|
||||
);
|
||||
});
|
||||
|
||||
it('preserves live and dangling foreign Claude symlinks while linking missing skills', () => {
|
||||
createSkill('dangling-foreign');
|
||||
createSkill('live-foreign');
|
||||
createSkill('missing');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
const external = join(root, 'external');
|
||||
mkdirSync(external);
|
||||
const liveLink = join(paths.claudeSkillsDir, 'live-foreign');
|
||||
const danglingLink = join(paths.claudeSkillsDir, 'dangling-foreign');
|
||||
symlinkSync(external, liveLink);
|
||||
symlinkSync(join(root, 'external-missing'), danglingLink);
|
||||
|
||||
const result = spawnSync('bash', [LEGACY_SYNC_SCRIPT, '--link-only'], {
|
||||
encoding: 'utf8',
|
||||
env: { ...process.env, HOME: root, MOSAIC_HOME: join(root, '.config', 'mosaic') },
|
||||
});
|
||||
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
expect(readlinkSync(liveLink)).toBe(external);
|
||||
expect(readlinkSync(danglingLink)).toBe(join(root, 'external-missing'));
|
||||
expect(readlinkSync(join(paths.claudeSkillsDir, 'missing'))).toBe(
|
||||
join(paths.mosaicSkillsDir, 'missing'),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('syncClaudeSkills', () => {
|
||||
it('generically creates every missing canonical link and repairs managed broken links', () => {
|
||||
createSkill('added-after-setup');
|
||||
createSkill('another-new-skill');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
symlinkSync(
|
||||
join(paths.mosaicSkillsDir, 'retired'),
|
||||
join(paths.claudeSkillsDir, 'added-after-setup'),
|
||||
);
|
||||
|
||||
const result = syncClaudeSkills(paths);
|
||||
|
||||
expect(result).toEqual({
|
||||
registered: ['another-new-skill'],
|
||||
repaired: ['added-after-setup'],
|
||||
unchanged: [],
|
||||
conflicts: [],
|
||||
});
|
||||
expectCorrectLink('added-after-setup');
|
||||
expectCorrectLink('another-new-skill');
|
||||
});
|
||||
|
||||
it('escapes an invalid filesystem-derived name in conflict output', () => {
|
||||
createSkill('line\nbreak');
|
||||
|
||||
const result = syncClaudeSkills(paths);
|
||||
|
||||
expect(result.registered).toEqual([]);
|
||||
expect(result.conflicts).toEqual([
|
||||
expect.objectContaining({
|
||||
name: '"line\\nbreak"',
|
||||
reason: expect.stringMatching(/invalid/i),
|
||||
}),
|
||||
]);
|
||||
expect(existsSync(paths.claudeSkillsDir)).toBe(false);
|
||||
});
|
||||
|
||||
it('continues syncing other skills without clobbering foreign entries', () => {
|
||||
createSkill('blocked');
|
||||
createSkill('link-me');
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
const blocked = join(paths.claudeSkillsDir, 'blocked');
|
||||
writeFileSync(blocked, 'keep me\n');
|
||||
|
||||
const result = syncClaudeSkills(paths);
|
||||
|
||||
expect(result.registered).toEqual(['link-me']);
|
||||
expect(result.conflicts).toEqual([
|
||||
expect.objectContaining({
|
||||
name: 'blocked',
|
||||
reason: expect.stringMatching(/foreign|refus/i),
|
||||
}),
|
||||
]);
|
||||
expect(readlinkSync(join(paths.claudeSkillsDir, 'link-me'))).toBe(
|
||||
join(paths.mosaicSkillsDir, 'link-me'),
|
||||
);
|
||||
expect(lstatSync(blocked).isFile()).toBe(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
419
packages/mosaic/src/commands/skill.ts
Normal file
419
packages/mosaic/src/commands/skill.ts
Normal file
@@ -0,0 +1,419 @@
|
||||
import {
|
||||
existsSync,
|
||||
lstatSync,
|
||||
mkdirSync,
|
||||
readdirSync,
|
||||
readlinkSync,
|
||||
symlinkSync,
|
||||
unlinkSync,
|
||||
type Stats,
|
||||
} from 'node:fs';
|
||||
import { homedir } from 'node:os';
|
||||
import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
|
||||
import type { Command } from 'commander';
|
||||
import { DEFAULT_MOSAIC_HOME } from '../constants.js';
|
||||
|
||||
export interface SkillPaths {
|
||||
mosaicSkillsDir: string;
|
||||
claudeSkillsDir: string;
|
||||
}
|
||||
|
||||
export type SkillRegistrationStatus = 'registered' | 'already-registered' | 'repaired';
|
||||
export type SkillUnregistrationStatus = 'unregistered' | 'already-unregistered';
|
||||
export type SkillListStatus =
|
||||
| 'registered'
|
||||
| 'unregistered'
|
||||
| 'dangling'
|
||||
| 'foreign'
|
||||
| 'foreign-dangling'
|
||||
| 'misdirected';
|
||||
|
||||
export interface SkillRegistrationResult {
|
||||
name: string;
|
||||
status: SkillRegistrationStatus;
|
||||
sourcePath: string;
|
||||
linkPath: string;
|
||||
}
|
||||
|
||||
export interface SkillUnregistrationResult {
|
||||
name: string;
|
||||
status: SkillUnregistrationStatus;
|
||||
linkPath: string;
|
||||
}
|
||||
|
||||
export interface SkillListEntry {
|
||||
name: string;
|
||||
status: SkillListStatus;
|
||||
sourcePath?: string;
|
||||
linkPath: string;
|
||||
targetPath?: string;
|
||||
}
|
||||
|
||||
export interface SkillSyncConflict {
|
||||
name: string;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
export interface SkillSyncResult {
|
||||
registered: string[];
|
||||
repaired: string[];
|
||||
unchanged: string[];
|
||||
conflicts: SkillSyncConflict[];
|
||||
}
|
||||
|
||||
const SAFE_SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
|
||||
|
||||
export class SkillBridgeError extends Error {
|
||||
public constructor(message: string) {
|
||||
super(message);
|
||||
this.name = 'SkillBridgeError';
|
||||
}
|
||||
}
|
||||
|
||||
/** Resolve the production bridge paths while keeping tests injectable. */
|
||||
export function getDefaultSkillPaths(): SkillPaths {
|
||||
const mosaicHome = process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
|
||||
const claudeHome = process.env['CLAUDE_HOME'] ?? join(homedir(), '.claude');
|
||||
return {
|
||||
mosaicSkillsDir: join(mosaicHome, 'skills'),
|
||||
claudeSkillsDir: join(claudeHome, 'skills'),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject a user-supplied name before any filesystem operation.
|
||||
* A skill name must identify one direct child in both managed roots.
|
||||
*/
|
||||
export function validateSkillName(name: string): void {
|
||||
if (
|
||||
name.length === 0 ||
|
||||
name.startsWith('-') ||
|
||||
name.endsWith('.') ||
|
||||
name.includes('..') ||
|
||||
name.includes('/') ||
|
||||
name.includes('\\') ||
|
||||
isAbsolute(name) ||
|
||||
!SAFE_SKILL_NAME.test(name)
|
||||
) {
|
||||
throw new SkillBridgeError(
|
||||
`Invalid skill name ${JSON.stringify(name)}: use letters, numbers, dots, underscores, or hyphens; start with a letter or number; and do not use paths, "..", or a leading "-".`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function displaySkillName(name: string): string {
|
||||
return SAFE_SKILL_NAME.test(name) ? name : JSON.stringify(name);
|
||||
}
|
||||
|
||||
function lstatIfPresent(path: string): Stats | undefined {
|
||||
try {
|
||||
return lstatSync(path);
|
||||
} catch (error: unknown) {
|
||||
if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return undefined;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function assertNoSymlinkAncestors(path: string): void {
|
||||
const absolute = resolve(path);
|
||||
const pathRoot = parse(absolute).root;
|
||||
let current = pathRoot;
|
||||
|
||||
for (const segment of relative(pathRoot, absolute).split(sep)) {
|
||||
if (segment.length === 0) continue;
|
||||
current = join(current, segment);
|
||||
const entry = lstatIfPresent(current);
|
||||
if (!entry) break;
|
||||
if (entry.isSymbolicLink()) {
|
||||
throw new SkillBridgeError(
|
||||
`Refusing symlink ancestor at ${current}; managed skill roots must resolve without symlink traversal.`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function assertManagedRoots(paths: SkillPaths): void {
|
||||
assertNoSymlinkAncestors(paths.mosaicSkillsDir);
|
||||
assertNoSymlinkAncestors(paths.claudeSkillsDir);
|
||||
}
|
||||
|
||||
function directChild(root: string, name: string): string {
|
||||
const resolvedRoot = resolve(root);
|
||||
const child = resolve(resolvedRoot, name);
|
||||
if (dirname(child) !== resolvedRoot) {
|
||||
throw new SkillBridgeError(`Invalid skill name "${name}": resolved path escapes its root.`);
|
||||
}
|
||||
return child;
|
||||
}
|
||||
|
||||
function resolveLinkTarget(linkPath: string): string {
|
||||
return resolve(dirname(linkPath), readlinkSync(linkPath));
|
||||
}
|
||||
|
||||
function isInsideSkillsRoot(targetPath: string, skillsRoot: string): boolean {
|
||||
const rel = relative(resolve(skillsRoot), resolve(targetPath));
|
||||
return rel.length > 0 && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
|
||||
}
|
||||
|
||||
function isDangling(linkPath: string): boolean {
|
||||
return !existsSync(linkPath);
|
||||
}
|
||||
|
||||
function assertSourceSkill(name: string, paths: SkillPaths): string {
|
||||
const sourcePath = directChild(paths.mosaicSkillsDir, name);
|
||||
const source = lstatIfPresent(sourcePath);
|
||||
if (!source?.isDirectory()) {
|
||||
throw new SkillBridgeError(
|
||||
`Canonical skill directory not found: ${sourcePath}. Add the skill under the Mosaic skills directory before registering it.`,
|
||||
);
|
||||
}
|
||||
return sourcePath;
|
||||
}
|
||||
|
||||
function foreignTargetError(linkPath: string): SkillBridgeError {
|
||||
return new SkillBridgeError(
|
||||
`Refusing to modify foreign entry at ${linkPath}; only symlinks pointing inside the Mosaic skills directory are managed.`,
|
||||
);
|
||||
}
|
||||
|
||||
/** Register one canonical skill with Claude Code without clobbering foreign entries. */
|
||||
export function registerSkill(
|
||||
name: string,
|
||||
paths: SkillPaths = getDefaultSkillPaths(),
|
||||
): SkillRegistrationResult {
|
||||
validateSkillName(name);
|
||||
assertManagedRoots(paths);
|
||||
const sourcePath = assertSourceSkill(name, paths);
|
||||
const linkPath = directChild(paths.claudeSkillsDir, name);
|
||||
const existing = lstatIfPresent(linkPath);
|
||||
|
||||
if (!existing) {
|
||||
mkdirSync(paths.claudeSkillsDir, { recursive: true });
|
||||
symlinkSync(sourcePath, linkPath);
|
||||
return { name, status: 'registered', sourcePath, linkPath };
|
||||
}
|
||||
|
||||
if (!existing.isSymbolicLink()) throw foreignTargetError(linkPath);
|
||||
|
||||
const existingTarget = resolveLinkTarget(linkPath);
|
||||
if (!isInsideSkillsRoot(existingTarget, paths.mosaicSkillsDir)) {
|
||||
throw foreignTargetError(linkPath);
|
||||
}
|
||||
|
||||
if (existingTarget === resolve(sourcePath) && !isDangling(linkPath)) {
|
||||
return { name, status: 'already-registered', sourcePath, linkPath };
|
||||
}
|
||||
|
||||
if (!isDangling(linkPath)) {
|
||||
throw new SkillBridgeError(
|
||||
`Refusing to replace live Mosaic skill symlink at ${linkPath}; it points to ${existingTarget}, not ${sourcePath}.`,
|
||||
);
|
||||
}
|
||||
|
||||
unlinkSync(linkPath);
|
||||
symlinkSync(sourcePath, linkPath);
|
||||
return { name, status: 'repaired', sourcePath, linkPath };
|
||||
}
|
||||
|
||||
/** Unregister only a symlink owned by the canonical Mosaic skills root. */
|
||||
export function unregisterSkill(
|
||||
name: string,
|
||||
paths: SkillPaths = getDefaultSkillPaths(),
|
||||
): SkillUnregistrationResult {
|
||||
validateSkillName(name);
|
||||
assertManagedRoots(paths);
|
||||
const linkPath = directChild(paths.claudeSkillsDir, name);
|
||||
const existing = lstatIfPresent(linkPath);
|
||||
|
||||
if (!existing) return { name, status: 'already-unregistered', linkPath };
|
||||
if (!existing.isSymbolicLink()) throw foreignTargetError(linkPath);
|
||||
|
||||
const targetPath = resolveLinkTarget(linkPath);
|
||||
if (!isInsideSkillsRoot(targetPath, paths.mosaicSkillsDir)) throw foreignTargetError(linkPath);
|
||||
|
||||
const expectedTarget = resolve(directChild(paths.mosaicSkillsDir, name));
|
||||
if (targetPath !== expectedTarget) {
|
||||
throw new SkillBridgeError(
|
||||
`Refusing to unregister misdirected Mosaic skill symlink at ${linkPath}; it points to ${targetPath}, not ${expectedTarget}.`,
|
||||
);
|
||||
}
|
||||
|
||||
unlinkSync(linkPath);
|
||||
return { name, status: 'unregistered', linkPath };
|
||||
}
|
||||
|
||||
function canonicalSkillNames(paths: SkillPaths): string[] {
|
||||
assertNoSymlinkAncestors(paths.mosaicSkillsDir);
|
||||
const root = lstatIfPresent(paths.mosaicSkillsDir);
|
||||
if (!root) return [];
|
||||
if (!root.isDirectory()) {
|
||||
throw new SkillBridgeError(
|
||||
`Canonical skills path is not a directory: ${paths.mosaicSkillsDir}`,
|
||||
);
|
||||
}
|
||||
return readdirSync(paths.mosaicSkillsDir, { withFileTypes: true })
|
||||
.filter((entry) => entry.isDirectory())
|
||||
.map((entry) => entry.name)
|
||||
.sort();
|
||||
}
|
||||
|
||||
function claudeEntryNames(paths: SkillPaths): string[] {
|
||||
assertNoSymlinkAncestors(paths.claudeSkillsDir);
|
||||
const root = lstatIfPresent(paths.claudeSkillsDir);
|
||||
if (!root) return [];
|
||||
if (!root.isDirectory()) {
|
||||
throw new SkillBridgeError(`Claude skills path is not a directory: ${paths.claudeSkillsDir}`);
|
||||
}
|
||||
return readdirSync(paths.claudeSkillsDir)
|
||||
.filter((name) => name.length > 0)
|
||||
.sort();
|
||||
}
|
||||
|
||||
/** Return a deterministic union of canonical skills and Claude bridge entries. */
|
||||
export function listSkills(paths: SkillPaths = getDefaultSkillPaths()): SkillListEntry[] {
|
||||
const canonicalNames = new Set(canonicalSkillNames(paths));
|
||||
const names = new Set([...canonicalNames, ...claudeEntryNames(paths)]);
|
||||
const entries: SkillListEntry[] = [];
|
||||
|
||||
for (const name of [...names].sort()) {
|
||||
const sourcePath = canonicalNames.has(name)
|
||||
? directChild(paths.mosaicSkillsDir, name)
|
||||
: undefined;
|
||||
const linkPath = directChild(paths.claudeSkillsDir, name);
|
||||
const installed = lstatIfPresent(linkPath);
|
||||
|
||||
if (!installed) {
|
||||
if (sourcePath) entries.push({ name, status: 'unregistered', sourcePath, linkPath });
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!installed.isSymbolicLink()) {
|
||||
entries.push({ name, status: 'foreign', sourcePath, linkPath });
|
||||
continue;
|
||||
}
|
||||
|
||||
const targetPath = resolveLinkTarget(linkPath);
|
||||
const owned = isInsideSkillsRoot(targetPath, paths.mosaicSkillsDir);
|
||||
const dangling = isDangling(linkPath);
|
||||
|
||||
if (!owned) {
|
||||
entries.push({
|
||||
name,
|
||||
status: dangling ? 'foreign-dangling' : 'foreign',
|
||||
sourcePath,
|
||||
linkPath,
|
||||
targetPath,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
if (dangling) {
|
||||
entries.push({ name, status: 'dangling', sourcePath, linkPath, targetPath });
|
||||
continue;
|
||||
}
|
||||
|
||||
entries.push({
|
||||
name,
|
||||
status: sourcePath && targetPath === resolve(sourcePath) ? 'registered' : 'misdirected',
|
||||
sourcePath,
|
||||
linkPath,
|
||||
targetPath,
|
||||
});
|
||||
}
|
||||
|
||||
return entries;
|
||||
}
|
||||
|
||||
/** Reconcile every canonical skill directory while preserving all foreign entries. */
|
||||
export function syncClaudeSkills(paths: SkillPaths = getDefaultSkillPaths()): SkillSyncResult {
|
||||
const result: SkillSyncResult = {
|
||||
registered: [],
|
||||
repaired: [],
|
||||
unchanged: [],
|
||||
conflicts: [],
|
||||
};
|
||||
|
||||
for (const name of canonicalSkillNames(paths)) {
|
||||
try {
|
||||
const registration = registerSkill(name, paths);
|
||||
if (registration.status === 'registered') result.registered.push(name);
|
||||
if (registration.status === 'repaired') result.repaired.push(name);
|
||||
if (registration.status === 'already-registered') result.unchanged.push(name);
|
||||
} catch (error: unknown) {
|
||||
result.conflicts.push({
|
||||
name: displaySkillName(name),
|
||||
reason: error instanceof Error ? error.message : String(error),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
function reportCommandError(error: unknown): void {
|
||||
console.error(error instanceof Error ? error.message : String(error));
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
/** Register the `mosaic skill` command group. */
|
||||
export function registerSkillCommand(
|
||||
program: Command,
|
||||
paths: SkillPaths = getDefaultSkillPaths(),
|
||||
): void {
|
||||
const skill = program
|
||||
.command('skill')
|
||||
.description('Manage Claude Code skill registrations')
|
||||
.configureHelp({ sortSubcommands: true });
|
||||
|
||||
skill
|
||||
.command('register <name>')
|
||||
.description('Register a Mosaic skill with Claude Code')
|
||||
.action((name: string) => {
|
||||
try {
|
||||
const result = registerSkill(name, paths);
|
||||
if (result.status === 'already-registered') {
|
||||
console.log(`${name}: already registered`);
|
||||
} else if (result.status === 'repaired') {
|
||||
console.log(`${name}: repaired dangling registration`);
|
||||
} else {
|
||||
console.log(`${name}: registered`);
|
||||
}
|
||||
} catch (error: unknown) {
|
||||
reportCommandError(error);
|
||||
}
|
||||
});
|
||||
|
||||
skill
|
||||
.command('unregister <name>')
|
||||
.description('Unregister a Mosaic skill from Claude Code')
|
||||
.action((name: string) => {
|
||||
try {
|
||||
const result = unregisterSkill(name, paths);
|
||||
console.log(
|
||||
result.status === 'already-unregistered'
|
||||
? `${name}: already unregistered`
|
||||
: `${name}: unregistered`,
|
||||
);
|
||||
} catch (error: unknown) {
|
||||
reportCommandError(error);
|
||||
}
|
||||
});
|
||||
|
||||
skill
|
||||
.command('list')
|
||||
.description('List registered, dangling, foreign, and unregistered skills')
|
||||
.action(() => {
|
||||
try {
|
||||
const entries = listSkills(paths);
|
||||
if (entries.length === 0) {
|
||||
console.log('No Mosaic or Claude Code skills found.');
|
||||
return;
|
||||
}
|
||||
for (const entry of entries) {
|
||||
console.log(`${entry.status.padEnd(17)} ${displaySkillName(entry.name)}`);
|
||||
}
|
||||
} catch (error: unknown) {
|
||||
reportCommandError(error);
|
||||
}
|
||||
});
|
||||
}
|
||||
Reference in New Issue
Block a user