@playcraft/cli 0.1.54 → 0.1.55-beta

package/dist/skill-registry/evaluation-commands.js

@@ -0,0 +1,174 @@
+import { constants, promises as fs } from 'node:fs';
+import { EvaluationClient, validatePollOptions } from './evaluation-client.js';
+import { parseSkillReference } from './package.js';
+import { packNativePlatformSource } from './platform-package.js';
+import { message, RegistryError } from './messages.js';
+async function readInput(file, keys) {
+    const maximum = 2 * 1024 * 1024;
+    const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > maximum)
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        const buffer = Buffer.alloc(stat.size + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = await handle.read(buffer, length, buffer.length - length, null);
+            if (!read.bytesRead)
+                break;
+            length += read.bytesRead;
+        }
+        if (length !== stat.size)
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        let value;
+        try {
+            value = JSON.parse(buffer.subarray(0, length).toString('utf8'));
+        }
+        catch {
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        }
+        if (!value ||
+            typeof value !== 'object' ||
+            Array.isArray(value) ||
+            Object.keys(value).some((key) => !keys.includes(key)) ||
+            keys.some((key) => !(key in value)))
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        return value;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function completed(run) {
+    if (run.phase !== 'completed' || run.verdict !== 'passed')
+        throw new RegistryError('evaluation_not_passed', message('evaluationNotPassed'), { run });
+    return run;
+}
+export function registerEvaluationCommands(registry, dependencies = {}) {
+    const stdout = dependencies.stdout ?? ((text) => console.log(text));
+    const stderr = dependencies.stderr ?? ((text) => console.error(text));
+    function action(command, callback) {
+        command.action(async (...values) => {
+            const options = values.at(-1).optsWithGlobals();
+            try {
+                const scope = options.scope ?? 'private';
+                if (!['private', 'team', 'platform'].includes(scope) ||
+                    (scope === 'team' ? !options.team?.trim() : Boolean(options.team)))
+                    throw new RegistryError('invalid_scope', message('invalidScope'));
+                const client = dependencies.evaluationClient?.(options) ??
+                    new EvaluationClient({ url: options.url, token: options.token });
+                const result = await callback(client, options, values.slice(0, -2));
+                stdout(JSON.stringify(result, null, options.json ? undefined : 2));
+            }
+            catch (error) {
+                const failure = error instanceof RegistryError
+                    ? error
+                    : new RegistryError('operation_failed', message('requestFailed'));
+                (options.json ? stdout : stderr)(JSON.stringify({
+                    error: {
+                        code: failure.code,
+                        message: failure.message,
+                        status: failure.status,
+                        details: failure.details,
+                    },
+                }));
+                if (dependencies.failure)
+                    dependencies.failure();
+                else
+                    process.exitCode = 1;
+            }
+        });
+    }
+    async function exact(client, input, options) {
+        const ref = parseSkillReference(input, true);
+        return client.info(ref.skillRef, ref.version, {
+            scope: (options.scope ?? 'private'),
+            ...(options.team ? { teamId: options.team } : {}),
+        });
+    }
+    function polling(command) {
+        return command
+            .option('--timeout <seconds>', message('pollTimeout'), '600')
+            .option('--interval <seconds>', message('pollInterval'), '3');
+    }
+    function pollOptions(options) {
+        return { timeoutSeconds: Number(options.timeout), intervalSeconds: Number(options.interval) };
+    }
+    const platform = registry.command('platform').description(message('platform'));
+    action(platform
+        .command('push <source>')
+        .description(message('platformPush'))
+        .option('--ref <ref>', message('ref'))
+        .option('--version <version>', message('version'))
+        .requiredOption('--changelog <text>', message('changelog'))
+        .option('--evaluation-template <templateId>', message('evaluationTemplate')), async (client, options, [source]) => {
+        if (options.team || options.scope === 'team')
+            throw new RegistryError('invalid_scope', message('invalidScope'));
+        const bundle = await packNativePlatformSource(source, options);
+        return client.importPlatform(bundle, options.changelog, options.evaluationTemplate);
+    });
+    const evaluation = registry.command('evaluation').description(message('evaluation'));
+    const templates = evaluation.command('templates').description(message('evaluationTemplates'));
+    action(templates.command('list').description(message('evaluationTemplates')), (client) => client.templates());
+    action(templates
+        .command('create')
+        .description(message('createTemplate'))
+        .requiredOption('--input <file>', message('inputFile')), async (client, options) => {
+        const input = await readInput(options.input, ['key', 'name', 'spec']);
+        if (typeof input.key !== 'string' ||
+            typeof input.name !== 'string' ||
+            !input.spec ||
+            typeof input.spec !== 'object')
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        return client.createTemplate(input);
+    });
+    for (const state of ['enable', 'disable'])
+        action(templates.command(`${state} <templateId>`).description(message(state)), (client, _options, [id]) => client.templateState(id, state === 'enable' ? 'enabled' : 'disabled'));
+    action(evaluation
+        .command('models')
+        .description(message('evaluationModels'))
+        .requiredOption('--workspace <workspaceId>', message('workspace')), (client, options) => client.models(options.workspace));
+    const config = evaluation.command('config').description(message('evaluationConfig'));
+    action(config.command('get <reference>').description(message('readConfig')), async (client, options, [input]) => client.config(await exact(client, input, options)));
+    action(config
+        .command('set <reference>')
+        .description(message('saveConfig'))
+        .requiredOption('--input <file>', message('inputFile')), async (client, options, [input]) => {
+        const data = await readInput(options.input, ['templateId', 'expectedRevision', 'spec']);
+        if (typeof data.templateId !== 'string' ||
+            typeof data.expectedRevision !== 'number' ||
+            !data.spec ||
+            typeof data.spec !== 'object')
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        return client.saveConfig(await exact(client, input, options), data);
+    });
+    action(polling(evaluation
+        .command('run <reference>')
+        .description(message('evaluationRun'))
+        .requiredOption('--workspace <workspaceId>', message('workspace'))
+        .requiredOption('--config <configId>', message('configId'))
+        .requiredOption('--request-key <key>', message('requestKey'))
+        .option('--compare', message('compare'))
+        .option('--wait', message('wait'))), async (client, options, [input]) => {
+        if (options.wait)
+            validatePollOptions(pollOptions(options));
+        const run = await client.createRun(await exact(client, input, options), {
+            workspaceId: options.workspace,
+            configId: options.config,
+            compare: Boolean(options.compare),
+            requestKey: options.requestKey,
+        });
+        return options.wait ? completed(await client.wait(run.id, pollOptions(options))) : run;
+    });
+    action(evaluation.command('status <runId>').description(message('evaluationStatus')), (client, _options, [id]) => client.run(id));
+    action(evaluation
+        .command('runs <reference>')
+        .description(message('evaluationRuns'))
+        .requiredOption('--workspace <workspaceId>', message('workspace')), async (client, options, [input]) => client.runs(await exact(client, input, options), options.workspace));
+    action(evaluation
+        .command('evidence <runId>')
+        .description(message('evaluationEvidence'))
+        .requiredOption('--case <caseResultId>', message('caseResult')), (client, options, [id]) => client.evidence(id, options.case));
+    action(polling(evaluation.command('wait <runId>').description(message('wait'))), async (client, options, [id]) => completed(await client.wait(id, pollOptions(options))));
+    action(evaluation.command('cancel <runId>').description(message('evaluationCancel')), (client, _options, [id]) => client.cancel(id));
+}

package/dist/skill-registry/messages.js

@@ -0,0 +1,177 @@
+const messages = {
+    en: {
+        group: 'Manage remote skill versions and releases',
+        url: 'Deployment address (including any environment prefix)',
+        token: 'Personal access token (prefer PLAYCRAFT_TOKEN)',
+        json: 'Print one JSON (JavaScript Object Notation) result',
+        scope: 'Release scope: private, team, platform',
+        team: 'Target team identifier',
+        list: 'List accessible skills in a release scope',
+        query: 'Search names and descriptions',
+        limit: 'Page size (1–100)',
+        cursor: 'Continue from the returned cursor',
+        info: 'Read a skill or an exact version',
+        versions: 'List accessible versions',
+        files: 'Include the file inventory',
+        pull: 'Download and verify one exact version',
+        out: 'Destination directory (must be absent or empty)',
+        push: 'Upload an immutable draft version',
+        publish: 'Publish an exact version or upload and publish a directory',
+        update: 'Upload a new version with an explicit base version',
+        ref: 'Canonical skill identity (namespace/slug)',
+        version: 'Exact new semantic version',
+        base: 'Exact previous version for conflict detection',
+        changelog: 'Describe the version changes',
+        from: 'Directory containing SKILL.md and resources',
+        check: 'Check publish requirements for an exact version',
+        history: 'Read release history',
+        rollback: 'Move the release pointer to an existing exact version',
+        reason: 'Reason for the decision',
+        review: 'Manage release review requests',
+        submit: 'Submit an exact version for review',
+        approve: 'Approve a review as an authorized administrator',
+        reject: 'Reject a review as an authorized administrator',
+        login: 'Log in to this environment with playcraft login --url first.',
+        invalidUrl: 'Invalid environment address.',
+        invalidRef: 'Use a lowercase namespace/slug identity and an exact x.y.z release version (at most 32 characters) when required.',
+        invalidScope: 'Choose private, team, or platform; team requires --team and other scopes forbid it.',
+        invalidBundle: 'Invalid skill bundle.',
+        invalidResponse: 'The registry returned an invalid or mismatched response.',
+        tooLarge: 'The request or response exceeds the size limit.',
+        destination: 'Destination must be an absent or empty directory without symbolic links.',
+        network: 'The request could not complete. Retry the same command to recover its result.',
+        requestFailed: 'The registry rejected this request.',
+        missingVersion: 'Directory uploads require --version (or manifest.version), and --ref (or manifest.skillRef).',
+        missingBase: 'Updates require --base-version and a different --version.',
+        manifestConflict: 'Explicit identity/version conflicts with manifest.json. Update the manifest first.',
+        uploadOptionsOnly: '--ref, --version, --base-version and --changelog apply only to directory uploads; an exact reference already selects the version to publish.',
+        invalidReceipt: 'The pending release receipt is invalid. Inspect the registry history before attempting a new publication.',
+        platform: 'Register native platform skill bundles',
+        platformPush: 'Register a native platform draft from a directory or archive without publishing',
+        evaluationTemplate: 'Optional evaluation template identifier for the draft',
+        invalidPlatformBundle: 'Expected an unchanged native platform video skill bundle with an aligned manifest and SKILL.md.',
+        evaluation: 'Configure and run real skill evaluations',
+        evaluationTemplates: 'List evaluation runtime templates',
+        createTemplate: 'Create an evaluation template draft from a file',
+        enable: 'Enable an evaluation template',
+        disable: 'Disable an evaluation template',
+        inputFile: 'Input JSON (JavaScript Object Notation) file with the documented request fields',
+        evaluationModels: 'List evaluation models available to the workspace',
+        workspace: 'Workspace identifier authorized for this account',
+        evaluationConfig: 'Read and save exact-version evaluation configuration',
+        readConfig: 'Read the current configuration and revision',
+        saveConfig: 'Save configuration with an explicit expected revision',
+        evaluationRun: 'Enqueue a real evaluation of an exact skill version and configuration',
+        configId: 'Exact saved evaluation configuration identifier',
+        requestKey: 'Unique run key (8–128 letters, digits, underscores or hyphens); reuse only to recover the same run',
+        compare: 'Also evaluate the current stable version as baseline',
+        wait: 'Poll the run until terminal; fail unless its verdict is passed',
+        pollTimeout: 'Maximum polling duration in seconds (default 600; does not cancel the run)',
+        pollInterval: 'Polling interval in seconds (default 3; maximum 60)',
+        evaluationStatus: 'Read run state, verdict and case results',
+        evaluationRuns: 'List runs for an exact version in one workspace',
+        evaluationEvidence: 'Read archived evidence for one case result',
+        caseResult: 'Case result identifier from run.results[].id (not the logical case name)',
+        evaluationCancel: 'Request cancellation of a run',
+        invalidIdentifier: 'Expected a valid resource identifier.',
+        invalidEvaluationInput: 'Invalid evaluation input; use the documented fields and explicit identifiers/revision.',
+        invalidPollOptions: 'Polling timeout must be greater than 0 and at most 86400 seconds; interval must be greater than 0 and at most 60 seconds.',
+        waitTimeout: 'Polling timed out. The run is still active; use status or wait with its identifier.',
+        evaluationNotPassed: 'Evaluation ended without a passed verdict. Inspect the returned run and its evidence.',
+    },
+    zh: {
+        group: '管理远程技能版本与发行',
+        url: '部署地址（保留环境路径前缀）',
+        token: '个人访问令牌（建议使用 PLAYCRAFT_TOKEN）',
+        json: '输出单个 JSON (JavaScript Object Notation, JavaScript 对象表示法) 结果',
+        scope: '发行范围：private、team、platform',
+        team: '目标团队标识',
+        list: '列出发行范围内可访问的技能',
+        query: '搜索名称与描述',
+        limit: '每页数量（1–100）',
+        cursor: '使用返回的游标继续查询',
+        info: '读取技能或精确版本',
+        versions: '列出可访问版本',
+        files: '包括文件清单',
+        pull: '下载并校验一个精确版本',
+        out: '目标目录（必须不存在或为空）',
+        push: '上传不可变的草稿版本',
+        publish: '发布精确版本，或上传目录后发布',
+        update: '基于明确旧版本上传新版本',
+        ref: '规范技能标识（namespace/slug）',
+        version: '明确的新语义版本',
+        base: '用于冲突检测的明确旧版本',
+        changelog: '版本变更说明',
+        from: '包含 SKILL.md 和资源的目录',
+        check: '检查精确版本的发布条件',
+        history: '读取发行历史',
+        rollback: '将发行指针切换到已有精确版本',
+        reason: '操作原因',
+        review: '管理发行审核申请',
+        submit: '提交精确版本审核',
+        approve: '由有权限的管理员批准审核',
+        reject: '由有权限的管理员拒绝审核',
+        login: '请先使用 playcraft login --url 登录该环境。',
+        invalidUrl: '环境地址无效。',
+        invalidRef: '请使用小写 namespace/slug 标识，需要版本时必须给出精确 x.y.z 发行版本（最多 32 字符）。',
+        invalidScope: '范围须为 private、team 或 platform；team 必须提供 --team，其他范围不能提供。',
+        invalidBundle: '技能包无效。',
+        invalidResponse: '注册表返回了无效或不匹配的结果。',
+        tooLarge: '请求或响应超出大小上限。',
+        destination: '目标目录必须不存在或为空，路径不能包含符号链接。',
+        network: '请求未能完成。重新执行相同命令可恢复结果。',
+        requestFailed: '注册表拒绝了此请求。',
+        missingVersion: '上传目录需要 --version（或 manifest.version）及 --ref（或 manifest.skillRef）。',
+        missingBase: '更新需要 --base-version 和不同的 --version。',
+        manifestConflict: '参数中的标识或版本与 manifest.json 冲突，请先修改清单。',
+        uploadOptionsOnly: '--ref、--version、--base-version 和 --changelog 仅用于上传目录；精确引用已明确要发布的版本。',
+        invalidReceipt: '待恢复的发行回执无效。请先核对注册表发行历史，再发起新的发布。',
+        platform: '登记原生平台技能包',
+        platformPush: '从目录或压缩包登记原生平台草稿，不执行发布',
+        evaluationTemplate: '草稿可选使用的评估模板标识',
+        invalidPlatformBundle: '需要原生平台视频技能包，且清单与 SKILL.md 信息一致；不自动改写清单。',
+        evaluation: '配置并执行真实技能评估',
+        evaluationTemplates: '列出评估运行模板',
+        createTemplate: '根据文件创建评估模板草稿',
+        enable: '启用评估模板',
+        disable: '停用评估模板',
+        inputFile: '包含约定请求字段的 JSON (JavaScript Object Notation, JavaScript 对象表示法) 文件',
+        evaluationModels: '列出工作区可用的评估模型',
+        workspace: '当前账号有权限使用的工作区标识',
+        evaluationConfig: '读取和保存精确版本的评估配置',
+        readConfig: '读取当前配置和修订号',
+        saveConfig: '提供明确的预期修订号保存配置',
+        evaluationRun: '为精确技能版本和配置发起真实评估',
+        configId: '已保存评估配置的精确标识',
+        requestKey: '评估唯一请求键（8–128 位字母、数字、下划线或连字符）；仅恢复同一评估时复用',
+        compare: '同时评估当前稳定版本作为基线',
+        wait: '轮询至评估终态；判定未通过时以失败状态退出',
+        pollTimeout: '最长轮询秒数（默认 600；超时不取消评估）',
+        pollInterval: '轮询间隔秒数（默认 3；最多 60）',
+        evaluationStatus: '读取评估状态、判定和用例结果',
+        evaluationRuns: '列出工作区内精确版本的评估记录',
+        evaluationEvidence: '读取单个用例结果的归档证据',
+        caseResult: '使用 run.results[].id 用例结果标识，不使用逻辑用例名称',
+        evaluationCancel: '请求取消评估',
+        invalidIdentifier: '资源标识无效。',
+        invalidEvaluationInput: '评估输入无效；请使用文档约定字段及明确的标识和修订号。',
+        invalidPollOptions: '轮询时限须大于 0 且不超过 86400 秒，间隔须大于 0 且不超过 60 秒。',
+        waitTimeout: '轮询超时，评估仍在运行；可用评估标识继续查询或等待。',
+        evaluationNotPassed: '评估已结束但未通过，请查看返回的评估记录和证据。',
+    },
+};
+export function message(key) {
+    return messages[(process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en').startsWith('zh') ? 'zh' : 'en'][key];
+}
+export class RegistryError extends Error {
+    code;
+    details;
+    status;
+    constructor(code, text, details, status) {
+        super(text);
+        this.code = code;
+        this.details = details;
+        this.status = status;
+        this.name = 'RegistryError';
+    }
+}

package/dist/skill-registry/package.js

@@ -0,0 +1,275 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import yaml from 'js-yaml';
+import { createCanonicalBundleArchive, extractBundleArchive, } from '@playcraft/common/project-skills';
+import { message, RegistryError } from './messages.js';
+export const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_FILE_BYTES = 16 * 1024 * 1024;
+const MAX_FILES = 512;
+const RECEIPT = '.playcraft-skill.json';
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+export function parseSkillReference(value, exact = false) {
+    const [skillRef, version, extra] = value.split('@');
+    if (!/^[a-z0-9][a-z0-9_-]{0,95}\/[a-z0-9][a-z0-9._-]{0,159}$/.test(skillRef) ||
+        extra !== undefined ||
+        (version !== undefined && (!SEMVER.test(version) || version.length > 32)) ||
+        (exact && !version)) {
+        throw new RegistryError('invalid_reference', message('invalidRef'));
+    }
+    return { skillRef, version };
+}
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function bundleError(details) {
+    throw new RegistryError('invalid_bundle', message('invalidBundle'), details);
+}
+function safePath(value) {
+    return (value === value.trim() &&
+        !/[\\:\x00-\x1f\x7f]/.test(value) &&
+        !value.startsWith('/') &&
+        value
+            .split('/')
+            .every((part) => Boolean(part) &&
+            part !== '.' &&
+            part !== '..' &&
+            !/[. ]$/.test(part) &&
+            !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)));
+}
+function validateFiles(files) {
+    if (files.length > MAX_FILES)
+        bundleError({ maxFiles: MAX_FILES });
+    const names = new Set();
+    let size = 0;
+    for (const file of files) {
+        const normalized = file.path.normalize('NFC').toLowerCase();
+        if (!safePath(file.path) || names.has(normalized) || file.path === RECEIPT)
+            bundleError({ path: file.path });
+        names.add(normalized);
+        size += file.data.length;
+        if (file.data.length > MAX_FILE_BYTES || size > MAX_BUNDLE_BYTES)
+            bundleError({
+                path: file.path,
+                maxFileBytes: MAX_FILE_BYTES,
+                maxBundleBytes: MAX_BUNDLE_BYTES,
+            });
+    }
+    for (const name of names) {
+        const parts = name.split('/');
+        for (let index = 1; index < parts.length; index++)
+            if (names.has(parts.slice(0, index).join('/')))
+                bundleError({ path: name });
+    }
+    if (!files
+        .find((file) => file.path === 'SKILL.md')
+        ?.data.toString('utf8')
+        .trim())
+        bundleError({ path: 'SKILL.md' });
+}
+function readManifest(file) {
+    if (!file)
+        return {};
+    try {
+        const value = JSON.parse(file.toString('utf8'));
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            return value;
+    }
+    catch {
+        /* Report a structured validation error below. */
+    }
+    return bundleError({ path: 'manifest.json' });
+}
+function validateReferences(manifest, files) {
+    if (manifest.files === undefined)
+        return;
+    if (!Array.isArray(manifest.files))
+        bundleError({ path: 'manifest.json:files' });
+    for (const reference of manifest.files) {
+        if (!reference ||
+            typeof reference !== 'object' ||
+            typeof reference.path !== 'string' ||
+            !safePath(reference.path))
+            bundleError({ reference });
+        const file = files.find((item) => item.path === reference.path);
+        if (!file || (reference.hash !== undefined && reference.hash !== sha256(file.data)))
+            bundleError({ reference });
+    }
+}
+export async function packSkillDirectory(directory, options) {
+    const root = path.resolve(directory);
+    const rootStat = await fs.lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        bundleError({ path: root });
+    const files = [];
+    let total = 0;
+    let entries = 0;
+    async function walk(relative = '') {
+        for (const entry of (await fs.readdir(path.join(root, relative))).sort()) {
+            if (!relative && ['.git', 'node_modules', RECEIPT].includes(entry))
+                continue;
+            const name = relative ? `${relative}/${entry}` : entry;
+            if (!safePath(name) || ++entries > 2048)
+                bundleError({ path: name });
+            const fullPath = path.join(root, name);
+            const stat = await fs.lstat(fullPath);
+            if (stat.isSymbolicLink())
+                bundleError({ path: name });
+            if (stat.isDirectory()) {
+                await walk(name);
+                continue;
+            }
+            if (!stat.isFile() ||
+                stat.nlink !== 1 ||
+                stat.size > MAX_FILE_BYTES ||
+                files.length >= MAX_FILES ||
+                total + stat.size > MAX_BUNDLE_BYTES)
+                bundleError({ path: name });
+            const handle = await fs.open(fullPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const opened = await handle.stat();
+                if (!opened.isFile() ||
+                    opened.ino !== stat.ino ||
+                    opened.dev !== stat.dev ||
+                    opened.size !== stat.size)
+                    bundleError({ path: name });
+                // A bounded read also prevents concurrently growing files from allocating unbounded memory.
+                const data = Buffer.alloc(stat.size + 1);
+                let length = 0;
+                while (length < data.length) {
+                    const chunk = await handle.read(data, length, data.length - length, null);
+                    if (!chunk.bytesRead)
+                        break;
+                    length += chunk.bytesRead;
+                }
+                if (length !== stat.size)
+                    bundleError({ path: name });
+                files.push({ path: name, data: data.subarray(0, length) });
+                total += length;
+            }
+            finally {
+                await handle.close();
+            }
+        }
+    }
+    await walk();
+    validateFiles(files);
+    const manifest = readManifest(files.find((file) => file.path === 'manifest.json')?.data);
+    const ref = options.ref ?? manifest.skillRef;
+    const version = options.version ?? manifest.version;
+    if (typeof ref !== 'string' || typeof version !== 'string')
+        throw new RegistryError('missing_version', message('missingVersion'));
+    const identity = parseSkillReference(`${ref}@${version}`, true);
+    if ((manifest.skillRef !== undefined && manifest.skillRef !== ref) ||
+        (manifest.version !== undefined && manifest.version !== version)) {
+        throw new RegistryError('manifest_conflict', message('manifestConflict'));
+    }
+    const markdown = files.find((file) => file.path === 'SKILL.md').data.toString('utf8');
+    let frontmatter = {};
+    const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (match) {
+        try {
+            const parsed = yaml.load(match[1]);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                frontmatter = parsed;
+        }
+        catch {
+            bundleError({ path: 'SKILL.md:frontmatter' });
+        }
+    }
+    const output = {
+        schemaVersion: 2,
+        category: 'general',
+        kind: 'markdown',
+        bundleType: 'markdown',
+        name: frontmatter.name ?? ref.split('/')[1],
+        description: frontmatter.description ?? '',
+        ...manifest,
+        skillRef: identity.skillRef,
+        version,
+        files: manifest.files ??
+            files.filter((file) => file.path !== 'manifest.json').map((file) => ({ path: file.path })),
+    };
+    const packaged = options.preserveManifest
+        ? files
+        : files.filter((file) => file.path !== 'manifest.json');
+    if (!options.preserveManifest)
+        packaged.push({ path: 'manifest.json', data: Buffer.from(`${JSON.stringify(output)}\n`) });
+    else if (manifest.skillRef !== ref || manifest.version !== version)
+        bundleError({ path: 'manifest.json' });
+    validateFiles(packaged);
+    validateReferences(options.preserveManifest ? manifest : output, packaged);
+    const archive = createCanonicalBundleArchive(packaged);
+    if (archive.length > MAX_BUNDLE_BYTES)
+        throw new RegistryError('bundle_too_large', message('tooLarge'));
+    return {
+        skillRef: identity.skillRef,
+        version,
+        archive,
+        uploadHash: sha256(archive),
+        files: packaged.map((file) => ({ path: file.path, size: file.data.length })),
+    };
+}
+async function assertDestination(target) {
+    for (let current = target;; current = path.dirname(current)) {
+        const stat = await fs.lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+            throw new RegistryError('unsafe_destination', message('destination'));
+        if (current === path.dirname(current))
+            break;
+    }
+    const existing = await fs.readdir(target).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (existing?.length)
+        throw new RegistryError('destination_not_empty', message('destination'));
+    return existing !== null;
+}
+export async function unpackSkillArchive(archive, destination, expected) {
+    if (!/^[a-f0-9]{64}$/.test(expected.artifactHash) || sha256(archive) !== expected.artifactHash)
+        throw new RegistryError('artifact_hash_mismatch', message('invalidResponse'));
+    const extracted = extractBundleArchive(archive, {
+        maxArchiveBytes: MAX_BUNDLE_BYTES,
+        maxExpandedBytes: MAX_BUNDLE_BYTES + 8 * 1024 * 1024,
+    });
+    if (extracted.issues.length)
+        bundleError(extracted.issues);
+    validateFiles(extracted.files);
+    const manifestFile = extracted.files.find((file) => file.path === 'manifest.json');
+    if (!manifestFile)
+        bundleError({ path: 'manifest.json' });
+    const manifest = readManifest(manifestFile.data);
+    // Historical artifacts predate these declarations; their exact bytes remain pinned by the server hash.
+    if ((manifest.skillRef !== undefined && manifest.skillRef !== expected.skillRef) ||
+        (manifest.version !== undefined && manifest.version !== expected.version))
+        throw new RegistryError('artifact_identity_mismatch', message('invalidResponse'));
+    validateReferences(manifest, extracted.files);
+    const target = path.resolve(destination);
+    await assertDestination(target);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const temporary = await fs.mkdtemp(path.join(path.dirname(target), '.playcraft-skill-'));
+    try {
+        for (const file of extracted.files) {
+            const fullPath = path.join(temporary, file.path);
+            await fs.mkdir(path.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, file.data, { flag: 'wx', mode: 0o644 });
+        }
+        await fs.writeFile(path.join(temporary, RECEIPT), `${JSON.stringify(expected, null, 2)}\n`, {
+            flag: 'wx',
+            mode: 0o600,
+        });
+        if (await assertDestination(target))
+            await fs.rmdir(target);
+        await fs.rename(temporary, target);
+    }
+    finally {
+        await fs.rm(temporary, { recursive: true, force: true });
+    }
+    return { directory: target, files: extracted.files.length };
+}