@yargote/artifacts-cli 0.0.0-stage → 0.1.0-beta.10

package/src/operations.js

@@ -0,0 +1,98 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { createSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { canonicalResource } from '@yargote/artifacts-contracts/http';
+const binding = {
+    version: z.literal(1),
+    resource: z.string().transform(canonicalResource),
+    ownerId: z.string().min(1).max(128),
+};
+export const operationSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ ...binding, kind: z.literal('create'), command: createSchema }),
+    z.strictObject({ ...binding, kind: z.literal('update'), command: updateSchema }),
+    z.strictObject({ ...binding, kind: z.literal('publish'), command: publishSchema }),
+    z.strictObject({ ...binding, kind: z.literal('move'), command: moveSchema }),
+    z.strictObject({ ...binding, kind: z.literal('share'), command: shareSchema }),
+    z.strictObject({ ...binding, kind: z.literal('unshare'), command: unshareSchema }),
+]);
+export function operationPath(stateDir, resource, requestId) {
+    createSchema.shape.requestId.parse(requestId);
+    return join(stateDir, 'operations', `${createHash('sha256').update(JSON.stringify([canonicalResource(resource), requestId])).digest('hex')}.json`);
+}
+async function privateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()) || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0))
+        throw new Error(`The state directory must be private and owned by the current user: ${path}`);
+}
+export async function retainOperation(stateDir, resource, ownerId, mutation) {
+    const operation = operationSchema.parse({ version: 1, resource, ownerId, ...mutation });
+    await privateDirectory(stateDir);
+    const directory = join(stateDir, 'operations');
+    await privateDirectory(directory);
+    const path = operationPath(stateDir, resource, operation.command.requestId);
+    let file;
+    try {
+        file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error(`An operation already exists for ${operation.command.requestId}. Use artifacts retry ${operation.command.requestId} to send the retained command.`);
+        throw error;
+    }
+    try {
+        await file.writeFile(`${JSON.stringify(operation)}\n`, 'utf8');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    if (process.platform !== 'win32') {
+        const handle = await open(directory, constants.O_RDONLY);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return operation;
+}
+export async function loadOperation(stateDir, requestId, resource, ownerId) {
+    await privateDirectory(stateDir);
+    await privateDirectory(join(stateDir, 'operations'));
+    const file = await open(operationPath(stateDir, resource, requestId), constants.O_RDONLY | constants.O_NOFOLLOW);
+    let bytes;
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 8 * 1024 * 1024 || (process.getuid && stat.uid !== process.getuid()) || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0))
+            throw new Error('The retained operation must be a private regular file no larger than 8 MiB');
+        bytes = await file.readFile();
+    }
+    finally {
+        await file.close();
+    }
+    const operation = operationSchema.parse(JSON.parse(bytes.toString('utf8')));
+    if (operation.command.requestId !== requestId)
+        throw new Error('The retained request ID does not match the requested operation');
+    if (operation.resource !== canonicalResource(resource))
+        throw new Error('The retained operation belongs to a different server resource');
+    if (operation.ownerId !== ownerId)
+        throw new Error('The retained operation belongs to a different owner');
+    return operation;
+}
+export function submitOperation(client, operation) {
+    switch (operation.kind) {
+        case 'create': return client.create(operation.command);
+        case 'update': return client.update(operation.command);
+        case 'publish': return client.publish(operation.command);
+        case 'move': return client.move(operation.command);
+        case 'share': return client.share(operation.command);
+        case 'unshare': return client.unshare(operation.command);
+    }
+    const exhaustive = operation;
+    throw new Error(`Unsupported retained operation: ${exhaustive}`);
+}

package/src/skills.d.ts

@@ -0,0 +1,9 @@
+interface SkillsOptions {
+    full?: boolean;
+    all?: boolean;
+    agent?: string;
+    global?: boolean;
+    force?: boolean;
+}
+export declare function runSkillsCommand(positionals: string[], options: SkillsOptions, seen: ReadonlySet<string>): Promise<void>;
+export {};

package/src/skills.js

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const catalogDirectory = resolve(fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../../../skills/' : '../skills/', import.meta.url)));
+function parseCommand(positionals, options, seen) {
+    const [kind = 'list', ...arguments_] = positionals;
+    const allowed = { list: [], get: ['all', 'full'], path: [], install: ['agent', 'global', 'force'] };
+    if (!Object.hasOwn(allowed, kind))
+        throw new TypeError(`Unknown skills command ${kind}. Use artifacts --help for the reference.`);
+    for (const option of seen) {
+        if (!['server', 'state-dir', ...allowed[kind]].includes(option))
+            throw new TypeError(`Option --${option} is not supported by skills ${kind}`);
+    }
+    switch (kind) {
+        case 'list':
+            if (arguments_.length)
+                throw new TypeError('skills list does not accept positional arguments');
+            return { kind };
+        case 'get':
+            if (arguments_.length > 1 || (options.all ? arguments_.length !== 0 : arguments_.length !== 1))
+                throw new TypeError('skills get requires either one skill name or --all');
+            return { kind, selection: options.all ? { all: true } : { name: arguments_[0] }, full: options.full ?? false };
+        case 'path':
+            if (arguments_.length > 1)
+                throw new TypeError('skills path accepts zero or one skill name');
+            return { kind, name: arguments_[0] };
+        case 'install':
+            if (arguments_.length > 1)
+                throw new TypeError('skills install accepts zero or one skill name');
+            if (options.agent !== undefined && options.agent !== 'claude')
+                throw new TypeError('--agent requires claude. Omit --agent to install under .agents.');
+            return { kind, name: arguments_[0] ?? 'artifacts-cli', agent: options.agent === 'claude' ? 'claude' : 'agents', global: options.global ?? false, force: options.force ?? false };
+        default:
+            throw new TypeError(`Unknown skills command ${kind}`);
+    }
+}
+async function loadCatalog() {
+    const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const names = manifest.artifactsSkills;
+    if (!Array.isArray(names) || names.some((name) => typeof name !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) || new Set(names).size !== names.length)
+        throw new Error('Invalid bundled skills declaration');
+    return Promise.all(names.toSorted().map(async (name) => {
+        const directory = join(catalogDirectory, name);
+        const skillText = await readFile(join(directory, 'SKILL.md'));
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(skillText.toString('utf8'))?.[1];
+        const declaredName = frontmatter && /^name: (.+)$/m.exec(frontmatter)?.[1];
+        const description = frontmatter && /^description: (.+)$/m.exec(frontmatter)?.[1];
+        if (declaredName !== name || !description)
+            throw new Error(`Invalid bundled skill frontmatter at ${join(directory, 'SKILL.md')}`);
+        return { name, description, directory, skillText };
+    }));
+}
+async function fullFiles(directory, prefix = '') {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name, 'en'))) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            files.push(...await fullFiles(join(directory, entry.name), relative));
+        else if (entry.isFile())
+            files.push(relative);
+        else
+            throw new Error(`Bundled skill contains a non-regular file at ${join(directory, entry.name)}`);
+    }
+    return files;
+}
+function isText(content) {
+    if (content.includes(0))
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function labeledContent(skills, full) {
+    const chunks = [];
+    for (const skill of skills) {
+        const files = full ? ['SKILL.md', ...(await fullFiles(skill.directory)).filter((path) => path !== 'SKILL.md')] : ['SKILL.md'];
+        for (const path of files) {
+            const content = path === 'SKILL.md' ? skill.skillText : await readFile(join(skill.directory, path));
+            if (!isText(content)) {
+                chunks.push(Buffer.from(`=== ${skill.name}/${path} (binary, ${content.length} bytes) ===\n`));
+                continue;
+            }
+            chunks.push(Buffer.from(`=== ${skill.name}/${path} ===\n`), content);
+            if (content.at(-1) !== 10)
+                chunks.push(Buffer.from('\n'));
+        }
+    }
+    return Buffer.concat(chunks);
+}
+function discoveryText(skill) {
+    return `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\nBefore using this skill, run \`artifacts skills get ${skill.name} --full\`.\nLoad and follow the complete instructions, references, and templates bundled with the installed CLI version.\nRelative paths refer to the bundled directory reported by \`artifacts skills path ${skill.name}\`.\n`;
+}
+async function installSkill(skill, command) {
+    const destination = resolve(command.global ? homedir() : process.cwd(), command.agent === 'claude' ? '.claude' : '.agents', 'skills', skill.name, 'SKILL.md');
+    const content = Buffer.from(discoveryText(skill));
+    await mkdir(dirname(destination), { recursive: true });
+    try {
+        const file = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            await file.writeFile(content);
+        }
+        finally {
+            await file.close();
+        }
+        return destination;
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+    const existing = await lstat(destination);
+    if (!existing.isFile())
+        throw new TypeError(`Cannot install ${destination}. The destination must be a regular file, not a directory or symbolic link.`);
+    const file = await open(destination, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let previous;
+    try {
+        if (!(await file.stat()).isFile())
+            throw new TypeError(`Cannot install ${destination}. The destination must be a regular file.`);
+        previous = await file.readFile();
+    }
+    finally {
+        await file.close();
+    }
+    if (previous.equals(content))
+        return destination;
+    if (!command.force)
+        throw new TypeError(`Cannot replace differing file ${destination}. Use --force to replace it.`);
+    const temporary = join(dirname(destination), `.SKILL.md.${randomUUID()}.tmp`);
+    try {
+        const replacement = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            await replacement.writeFile(content);
+        }
+        finally {
+            await replacement.close();
+        }
+        const current = await lstat(destination);
+        if (!current.isFile())
+            throw new TypeError(`Cannot install ${destination}. The destination must be a regular file, not a directory or symbolic link.`);
+        if (current.ino !== existing.ino || current.dev !== existing.dev || current.mtimeMs !== existing.mtimeMs || current.ctimeMs !== existing.ctimeMs)
+            throw new TypeError(`Cannot replace ${destination}. The destination changed during installation. Run the command again.`);
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return destination;
+}
+export async function runSkillsCommand(positionals, options, seen) {
+    const command = parseCommand(positionals, options, seen);
+    const skills = await loadCatalog();
+    function named(name) {
+        const skill = skills.find((entry) => entry.name === name);
+        if (!skill)
+            throw new TypeError(`Unknown bundled skill ${name}. Use artifacts skills list to inspect available skills.`);
+        return skill;
+    }
+    switch (command.kind) {
+        case 'list':
+            process.stdout.write(skills.map((skill) => `${skill.name}\t${skill.description}\n`).join(''));
+            return;
+        case 'get': {
+            const selection = 'all' in command.selection ? skills : [named(command.selection.name)];
+            process.stdout.write(!command.full && 'name' in command.selection ? selection[0].skillText : await labeledContent(selection, command.full));
+            return;
+        }
+        case 'path':
+            process.stdout.write(`${command.name === undefined ? catalogDirectory : named(command.name).directory}\n`);
+            return;
+        case 'install':
+            process.stdout.write(`${await installSkill(named(command.name), command)}\n`);
+    }
+}