@yuchaocheng/yusijia 0.1.0-beta.1

package/dist/plan.js

@@ -0,0 +1,119 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { canonicalJson, checkBytes, CliError, LIMITS, normalizeSite, sha256 } from './core.js';
+import { manifestSchema } from './manifest.js';
+export { canonicalJson } from './core.js';
+const id = z.string().min(1).max(191);
+export const refSchema = z.union([
+    z.object({ ref: z.uuid(), field: z.enum(['id', 'version']) }).strict(),
+    z.object({ ref: z.uuid(), field: z.literal('photoId'), localCandidateId: z.string().min(1).max(100).regex(/^[a-zA-Z0-9_-]+$/) }).strict(),
+]);
+const value = z.union([id, refSchema]);
+const photoIds = (max) => z.array(value).max(max).transform(ids => Array.from(new Map(ids.map(v => [canonicalJson(v), v])).values()));
+const base = { operationId: z.uuid() };
+const target = { target: value, expectedVersion: z.union([z.iso.datetime(), refSchema.refine(r => r.field === 'version')]) };
+const albumFields = { name: z.string().trim().min(1).max(50), description: z.string().max(200).optional() };
+const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/).refine(v => { const d = new Date(`${v}T00:00:00.000Z`); return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === v; });
+const milestoneFields = { date, title: z.string().trim().min(1).max(100), description: z.string().max(2000).optional(), photoIds: photoIds(3).optional() };
+const textBlock = z.object({ id: id.optional(), type: z.enum(['paragraph', 'heading', 'bulletListItem', 'numberedListItem']), text: z.string().max(100000), level: z.number().int().min(1).max(3).optional() }).strict().refine(b => b.level === undefined || b.type === 'heading');
+const blocks = z.array(textBlock).min(1).max(500).refine(bs => bs.reduce((n, b) => n + b.text.length, 0) <= 100000 && new Set(bs.filter(b => b.id).map(b => b.id)).size === bs.filter(b => b.id).length);
+const edit = z.discriminatedUnion('type', [z.object({ type: z.literal('replaceText'), blockId: id, text: z.string().max(100000) }).strict(), z.object({ type: z.literal('append'), blocks }).strict()]);
+const diaryEdit = z.object({ edits: z.array(edit).min(1).max(500).optional(), status: z.enum(['DRAFT', 'PUBLISHED']).optional() }).strict().refine(p => p.edits !== undefined || p.status !== undefined);
+export const actionSchema = z.discriminatedUnion('action', [
+    z.object({ ...base, action: z.literal('albums.create'), payload: z.object(albumFields).strict() }).strict(),
+    z.object({ ...base, ...target, action: z.literal('albums.update'), payload: z.object(albumFields).partial().strict().refine(p => Object.keys(p).length > 0) }).strict(),
+    z.object({ ...base, ...target, action: z.literal('albums.photos'), payload: z.object({ add: photoIds(200), remove: photoIds(200) }).strict().refine(p => p.add.length + p.remove.length > 0 && p.add.length + p.remove.length <= 200 && !p.add.some(a => p.remove.some(b => canonicalJson(a) === canonicalJson(b)))) }).strict(),
+    z.object({ ...base, action: z.literal('timeline.create'), payload: z.object(milestoneFields).strict() }).strict(),
+    z.object({ ...base, ...target, action: z.literal('timeline.update'), payload: z.object(milestoneFields).partial().strict().refine(p => Object.keys(p).length > 0) }).strict(),
+    z.object({ ...base, action: z.literal('diary.create'), payload: z.object({ blocks, status: z.enum(['DRAFT', 'PUBLISHED']).default('DRAFT') }).strict() }).strict(),
+    z.object({ ...base, ...target, action: z.literal('diary.edit'), payload: diaryEdit }).strict(),
+    z.object({ ...base, ...target, action: z.literal('diary.publish'), payload: z.object({ status: z.literal('PUBLISHED') }).strict() }).strict(),
+    z.object({ ...base, action: z.literal('photos.import'), payload: z.object({ manifest: manifestSchema }).strict(), files: z.record(z.string(), z.string().min(1)), expectations: z.record(z.string(), z.union([z.object({ mode: z.literal('create') }).strict(), z.object({ mode: z.literal('reuse'), photoId: z.string().min(1).max(100), version: z.iso.datetime() }).strict()])) }).strict(),
+    z.object({ ...base, action: z.literal('photos.cancel'), target: value, payload: z.object({}).strict() }).strict(),
+]);
+const planCore = z.object({ schemaVersion: z.literal(1), origin: z.string().transform(normalizeSite), userId: id, items: z.array(actionSchema).min(1).max(LIMITS.maxActions) }).strict();
+export const planSchema = planCore.extend({ planHash: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export const resultSchema = z.object({ type: z.string().optional(), id: z.string().min(1).max(200), version: z.string().max(200).optional(), status: z.string().max(100).optional(), replayed: z.boolean().optional(), candidateId: z.string().max(200).optional(), candidates: z.array(z.object({ localCandidateId: z.string().max(100), id: z.string().max(200) })).max(200).optional(), photoIds: z.record(z.string(), z.string()).optional() });
+export function refsIn(v) {
+    if (!v || typeof v !== 'object')
+        return [];
+    if (Object.hasOwn(v, 'ref'))
+        return [refSchema.parse(v)];
+    return Object.values(v).flatMap(refsIn);
+}
+function validateOrder(items) {
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item.operationId) || refsIn(item).some(r => !seen.has(r.ref) || r.field === 'photoId' && !items.some(i => i.operationId === r.ref && i.action === 'photos.import' && i.payload.manifest.candidates.some(c => c.localCandidateId === r.localCandidateId && c.status === 'SELECTED'))))
+            throw new CliError('INVALID_INPUT');
+        seen.add(item.operationId);
+        checkBytes(item.payload);
+        if (item.action === 'photos.import')
+            for (const c of item.payload.manifest.candidates.filter(c => c.status === 'SELECTED')) {
+                if (!item.files[c.localCandidateId] || !item.expectations[c.localCandidateId])
+                    throw new CliError('INVALID_INPUT');
+            }
+    }
+}
+export function buildPlan(input) {
+    const raw = input;
+    const core = planCore.parse({ schemaVersion: 1, ...raw });
+    validateOrder(core.items);
+    return { ...core, planHash: sha256(canonicalJson(core)) };
+}
+export function verifyPlan(input, confirmed, identity) {
+    const { planHash, ...core } = planSchema.parse(input);
+    const p = buildPlan(core);
+    if (planHash !== confirmed || p.planHash !== confirmed || p.origin !== normalizeSite(identity.origin) || p.userId !== identity.userId)
+        throw new CliError('CONFIRMATION_REQUIRED');
+    return p;
+}
+export function resolveRefs(v, results) {
+    if (!v || typeof v !== 'object')
+        return v;
+    if (Object.hasOwn(v, 'ref')) {
+        const r = refSchema.parse(v);
+        const source = results[r.ref];
+        const result = r.field === 'photoId' ? source?.photoIds?.[r.localCandidateId] : source?.[r.field];
+        if (!result)
+            throw new CliError('RESULT_UNKNOWN');
+        return result;
+    }
+    if (Array.isArray(v))
+        return v.map(x => resolveRefs(x, results));
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, resolveRefs(x, results)]));
+}
+export function actionRequest(item, results) {
+    const a = actionSchema.parse(resolveRefs(item, results));
+    const resource = a.action.startsWith('albums.') ? 'albums' : a.action.startsWith('timeline.') ? 'milestones' : a.action.startsWith('diary.') ? 'diaries' : 'imports';
+    const suffix = 'target' in a ? `/${encodeURIComponent(a.target)}` : '';
+    return { path: `/${resource}${suffix}${a.action === 'albums.photos' ? '/photos' : a.action === 'photos.cancel' ? '/cancel' : ''}`, method: a.action.endsWith('.update') || a.action === 'diary.edit' || a.action === 'diary.publish' ? 'PATCH' : 'POST', body: a.payload, ...('expectedVersion' in a ? { version: a.expectedVersion } : {}) };
+}
+export function textBlocks(text) {
+    return text.split(/\r?\n\s*\r?\n/).map(text => ({ type: 'paragraph', text }));
+}
+export function revisePlan(previous, input, sent) {
+    const next = buildPlan(input);
+    const mapping = new Map();
+    function remap(v) {
+        if (Array.isArray(v))
+            return v.map(remap);
+        if (!v || typeof v !== 'object')
+            return v;
+        return Object.fromEntries(Object.entries(v).map(([k, val]) => [k, (k === 'ref' || k === 'operationId') && typeof val === 'string' ? mapping.get(val) ?? val : remap(val)]));
+    }
+    const items = next.items.map(item => {
+        const revised = remap(item);
+        const old = previous.items.find(o => o.operationId === item.operationId);
+        if (old && canonicalJson(old) !== canonicalJson(revised)) {
+            if (sent.has(item.operationId))
+                throw new CliError('RESULT_UNKNOWN');
+            mapping.set(item.operationId, randomUUID());
+            revised.operationId = mapping.get(item.operationId);
+        }
+        return revised;
+    });
+    if (previous.origin !== next.origin || previous.userId !== next.userId || previous.items.some(i => sent.has(i.operationId) && !items.some(n => n.operationId === i.operationId)))
+        throw new CliError('RESULT_UNKNOWN');
+    return buildPlan({ schemaVersion: 1, origin: next.origin, userId: next.userId, items });
+}

package/dist/scan.d.ts

@@ -0,0 +1,33 @@
+import { type Candidate, type Manifest } from './manifest.js';
+export declare function imageMime(b: Buffer): Candidate['mimeType'] | undefined;
+export declare function readPhoto(file: string, expected?: {
+    contentHash: string;
+    fileSize: number;
+    mimeType: string;
+}, scope?: string): Promise<Buffer<ArrayBuffer>>;
+export declare function imageDimensions(file: string): Promise<{
+    width: number;
+    height: number;
+}>;
+export declare function validateZipName(name: string): string;
+export declare function zipEntries(file: string): Promise<string[]>;
+type Issue = {
+    originalName: string;
+    relativePathHash: string;
+    reason: string;
+};
+export type ScanResult = {
+    manifest: Manifest;
+    manifestHash: string;
+    files: Record<string, string>;
+    inputKind: 'DIRECTORY' | 'ZIP' | 'FILES';
+    unsupported: Issue[];
+    duplicates: Issue[];
+    stagingDirectory?: string;
+};
+export declare function scan(options: {
+    input?: string;
+    files?: string[];
+    stagingDir?: string;
+}): Promise<ScanResult>;
+export {};

package/dist/scan.js

@@ -0,0 +1,262 @@
+import { constants } from 'node:fs';
+import { lstat, readdir, realpath, open, mkdtemp, writeFile, access } from 'node:fs/promises';
+import { basename, extname, join, relative, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import exifr from 'exifr';
+import { CliError, LIMITS, sha256, canonicalJson, checkBytes } from './core.js';
+import { manifestSchema } from './manifest.js';
+import { privateDirectory } from './storage.js';
+const run = promisify(execFile);
+const supported = { '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp' };
+export function imageMime(b) {
+    if (b.length >= 24 && b.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) && b.subarray(-8, -4).toString() === 'IEND')
+        return 'image/png';
+    if (b.length >= 20 && b[0] === 0xff && b[1] === 0xd8 && b[b.length - 2] === 0xff && b[b.length - 1] === 0xd9) {
+        let i = 2, hasFrame = false;
+        while (i + 4 < b.length && b[i] === 0xff) {
+            const marker = b[i + 1], length = b.readUInt16BE(i + 2);
+            if (length < 2 || i + 2 + length > b.length)
+                break;
+            if ([0xc0, 0xc1, 0xc2].includes(marker) && length >= 8 && b.readUInt16BE(i + 5) && b.readUInt16BE(i + 7))
+                hasFrame = true;
+            if (marker === 0xda)
+                return hasFrame ? 'image/jpeg' : undefined;
+            i += length + 2;
+        }
+    }
+    if (b.length >= 20 && b.subarray(0, 4).toString() === 'RIFF' && b.subarray(8, 12).toString() === 'WEBP' && b.readUInt32LE(4) + 8 === b.length && ['VP8 ', 'VP8L', 'VP8X'].includes(b.subarray(12, 16).toString()))
+        return 'image/webp';
+}
+export async function readPhoto(file, expected, scope) {
+    const actual = await realpath(file);
+    if (scope && !actual.startsWith(`${scope}/`))
+        throw new CliError('SOURCE_CHANGED');
+    const f = await open(actual, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await f.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > LIMITS.maxFileBytes)
+            throw new CliError('SOURCE_CHANGED');
+        const data = Buffer.alloc(stat.size + 1);
+        let used = 0;
+        while (used < data.length) {
+            const { bytesRead } = await f.read(data, used, data.length - used, null);
+            if (!bytesRead)
+                break;
+            used += bytesRead;
+        }
+        const buffer = data.subarray(0, used);
+        if (used !== stat.size || !imageMime(buffer) || (expected && (expected.fileSize !== used || expected.contentHash !== sha256(buffer) || expected.mimeType !== imageMime(buffer))))
+            throw new CliError('SOURCE_CHANGED');
+        return buffer;
+    }
+    finally {
+        await f.close();
+    }
+}
+export async function imageDimensions(file) {
+    const { stdout } = await run('/usr/bin/sips', ['-g', 'pixelWidth', '-g', 'pixelHeight', file], { timeout: 15000, maxBuffer: 65536 });
+    const width = Number(/^\s*pixelWidth:\s*(\d+)\s*$/m.exec(stdout)?.[1]);
+    const height = Number(/^\s*pixelHeight:\s*(\d+)\s*$/m.exec(stdout)?.[1]);
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1 || width > 100000 || height > 100000)
+        throw new CliError('SOURCE_CHANGED');
+    return { width, height };
+}
+export function validateZipName(name) {
+    if (!name || name.startsWith('/') || /^[a-z]:/i.test(name) || /[\\\x00-\x1f\x7f*?\[\]]/.test(name) || name.split('/').some(p => p === '..' || p === '.' || p === '' && !name.endsWith('/')))
+        throw new CliError('INVALID_INPUT');
+    return name;
+}
+// Read the central directory before invoking unzip: external attributes carry symlink/type bits.
+export async function zipEntries(file) {
+    const f = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const { size } = await f.stat();
+        if (size > LIMITS.maxFileBytes * LIMITS.maxCandidates || size < 22)
+            throw new CliError('INVALID_INPUT');
+        const tail = Buffer.alloc(Math.min(size, 65557));
+        await f.read(tail, 0, tail.length, size - tail.length);
+        let end = -1;
+        for (let i = tail.length - 22; i >= 0; i--)
+            if (tail.readUInt32LE(i) === 0x06054b50 && i + 22 + tail.readUInt16LE(i + 20) === tail.length) {
+                end = i;
+                break;
+            }
+        if (end < 0 || tail.readUInt16LE(end + 4) || tail.readUInt16LE(end + 6))
+            throw new CliError('INVALID_INPUT');
+        const count = tail.readUInt16LE(end + 10), length = tail.readUInt32LE(end + 12), offset = tail.readUInt32LE(end + 16);
+        if (count > 2000 || length > 2 * 1024 * 1024 || offset + length > size - 22 || count !== tail.readUInt16LE(end + 8))
+            throw new CliError('INVALID_INPUT');
+        const dir = Buffer.alloc(length);
+        await f.read(dir, 0, length, offset);
+        const names = [];
+        const seen = new Set();
+        let cursor = 0;
+        let total = 0;
+        for (let i = 0; i < count; i++) {
+            if (cursor + 46 > length || dir.readUInt32LE(cursor) !== 0x02014b50)
+                throw new CliError('INVALID_INPUT');
+            const flags = dir.readUInt16LE(cursor + 8), size = dir.readUInt32LE(cursor + 24), n = dir.readUInt16LE(cursor + 28), extra = dir.readUInt16LE(cursor + 30), comment = dir.readUInt16LE(cursor + 32), mode = dir.readUInt32LE(cursor + 38) >>> 16;
+            if (flags & 1 || (mode & 0xf000) === 0xa000 || ((mode & 0xf000) && ![0x8000, 0x4000].includes(mode & 0xf000)) || cursor + 46 + n + extra + comment > length)
+                throw new CliError('INVALID_INPUT');
+            const name = validateZipName(new TextDecoder('utf-8', { fatal: true }).decode(dir.subarray(cursor + 46, cursor + 46 + n)));
+            if (seen.has(name))
+                throw new CliError('INVALID_INPUT');
+            seen.add(name);
+            if (!name.endsWith('/')) {
+                total += size;
+                names.push(name);
+            }
+            if (total > LIMITS.maxFileBytes * LIMITS.maxCandidates)
+                throw new CliError('PAYLOAD_TOO_LARGE');
+            cursor += 46 + n + extra + comment;
+        }
+        if (cursor !== length)
+            throw new CliError('INVALID_INPUT');
+        const { stdout } = await run('/usr/bin/unzip', ['-Z1', file], { maxBuffer: 2 * 1024 * 1024, timeout: 30000 });
+        if (canonicalJson(stdout.split('\n').filter(n => n && !n.endsWith('/'))) !== canonicalJson(names))
+            throw new CliError('INVALID_INPUT');
+        return names;
+    }
+    finally {
+        await f.close();
+    }
+}
+export async function scan(options) {
+    if (!!options.input === !!options.files?.length)
+        throw new CliError('INVALID_INPUT');
+    try {
+        await access('/usr/bin/sips', constants.X_OK);
+    }
+    catch {
+        throw new CliError('TOOL_UNAVAILABLE');
+    }
+    const unsupported = [];
+    const duplicates = [];
+    const candidates = [];
+    const issue = (name, reason) => ({ originalName: basename(name), relativePathHash: sha256(name), reason });
+    let inspected = 0;
+    let total = 0;
+    async function accept(name, get) {
+        const expectedMime = supported[extname(name).toLowerCase()];
+        if (!expectedMime) {
+            unsupported.push(issue(name, /\.hei[cf]$/i.test(name) ? 'HEIC must be converted to JPEG, PNG or WebP.' : 'Unsupported format.'));
+            return;
+        }
+        if (++inspected > LIMITS.maxCandidates)
+            throw new CliError('PAYLOAD_TOO_LARGE');
+        let bytes, file;
+        try {
+            const data = await get();
+            bytes = data.bytes;
+            file = data.path;
+        }
+        catch {
+            unsupported.push(issue(name, 'Unreadable, corrupt or oversized file.'));
+            return;
+        }
+        total += bytes.length;
+        if (total > LIMITS.maxCandidates * LIMITS.maxFileBytes)
+            throw new CliError('PAYLOAD_TOO_LARGE');
+        const mimeType = imageMime(bytes);
+        if (!mimeType || mimeType !== expectedMime || bytes.length > LIMITS.maxFileBytes) {
+            unsupported.push(issue(name, 'Corrupt or mismatched image.'));
+            return;
+        }
+        let dimensions;
+        try {
+            dimensions = await imageDimensions(file);
+        }
+        catch {
+            unsupported.push(issue(name, 'Image dimensions could not be decoded by macOS sips.'));
+            return;
+        }
+        let metadata = {};
+        try {
+            const tags = await exifr.parse(bytes, { pick: ['DateTimeOriginal', 'CreateDate', 'Make', 'Model', 'latitude', 'longitude'] });
+            const takenAt = tags?.DateTimeOriginal ?? tags?.CreateDate;
+            const gps = await exifr.gps(bytes);
+            metadata = { ...(takenAt ? { takenAt: new Date(takenAt).toISOString() } : {}), ...(gps ? { gpsLatitude: gps.latitude, gpsLongitude: gps.longitude } : {}), ...(tags?.Make || tags?.Model ? { deviceModel: [tags.Make, tags.Model].filter(Boolean).join(' ').slice(0, 255) } : {}) };
+        }
+        catch { /* Images without EXIF still participate in rules-only grouping. */ }
+        candidates.push({ candidate: { contentHash: sha256(bytes), relativePathHash: sha256(name), originalName: basename(name), mimeType, fileSize: bytes.length, ...dimensions, ...metadata, groupKey: metadata.takenAt?.slice(0, 10) ?? (metadata.gpsLatitude !== undefined && metadata.gpsLongitude !== undefined ? `${metadata.gpsLatitude.toFixed(2)},${metadata.gpsLongitude.toFixed(2)}` : 'ungrouped'), recommendationScore: 0.8, recommendationReason: 'Rules only: supported image; no visual analysis.', status: 'SELECTED' }, path: file, source: name });
+    }
+    let inputKind = 'FILES', sourceLabel = 'Selected files', stagingDirectory;
+    if (options.input) {
+        const input = await realpath(resolve(options.input));
+        const stat = await lstat(input);
+        sourceLabel = basename(input);
+        if (stat.isDirectory()) {
+            inputKind = 'DIRECTORY';
+            let entries = 0;
+            async function walk(dir, depth = 0) {
+                if (depth > 64)
+                    throw new CliError('INVALID_INPUT');
+                for (const entry of (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+                    if (++entries > 10000)
+                        throw new CliError('PAYLOAD_TOO_LARGE');
+                    const file = join(dir, entry.name), name = relative(input, file);
+                    if (entry.isSymbolicLink()) {
+                        unsupported.push(issue(name, 'Symlink skipped.'));
+                        continue;
+                    }
+                    if (entry.isDirectory())
+                        await walk(file, depth + 1);
+                    else if (entry.isFile())
+                        await accept(name, async () => ({ bytes: await readPhoto(file, undefined, input), path: await realpath(file) }));
+                }
+            }
+            await walk(input);
+        }
+        else {
+            if (extname(input).toLowerCase() !== '.zip')
+                throw new CliError('INVALID_INPUT');
+            try {
+                await access('/usr/bin/unzip', constants.X_OK);
+            }
+            catch {
+                throw new CliError('TOOL_UNAVAILABLE');
+            }
+            inputKind = 'ZIP';
+            const names = await zipEntries(input);
+            const parent = options.stagingDir ? resolve(options.stagingDir) : await realpath(tmpdir());
+            if (options.stagingDir)
+                await privateDirectory(parent);
+            stagingDirectory = await mkdtemp(join(parent, 'yusijia-'));
+            for (const name of names)
+                await accept(name, async () => {
+                    const { stdout } = await run('/usr/bin/unzip', ['-p', input, name], { encoding: 'buffer', maxBuffer: LIMITS.maxFileBytes, timeout: 30000 });
+                    const bytes = Buffer.from(stdout), file = join(stagingDirectory, sha256(name));
+                    await writeFile(file, bytes, { mode: 0o600, flag: 'wx' });
+                    return { bytes, path: file };
+                });
+        }
+    }
+    else {
+        if (options.files.length > LIMITS.maxCandidates)
+            throw new CliError('PAYLOAD_TOO_LARGE');
+        for (const input of options.files) {
+            const file = resolve(input);
+            await accept(file, async () => ({ bytes: await readPhoto(file), path: await realpath(file) }));
+        }
+    }
+    function score(c) { return (c.candidate.takenAt ? 8 : 0) + (c.candidate.gpsLatitude !== undefined ? 4 : 0) + (c.candidate.deviceModel ? 2 : 0) + (/copy|副本|复件|duplicate/i.test(c.candidate.originalName) ? 0 : 1) - c.source.split('/').length * 0.01 - c.source.length * 0.0001; }
+    const unique = new Map();
+    for (const c of candidates.sort((a, b) => score(b) - score(a) || a.source.localeCompare(b.source))) {
+        if (unique.has(c.candidate.contentHash))
+            duplicates.push(issue(c.source, 'Same content; a better metadata/name representative was selected.'));
+        else
+            unique.set(c.candidate.contentHash, c);
+    }
+    const selected = [...unique.values()];
+    const manifestHash = sha256(canonicalJson({ schemaVersion: 1, sourceType: inputKind === 'ZIP' ? 'ZIP' : 'DIRECTORY', sourceLabel, candidates: selected.map(c => c.candidate) }));
+    const files = {};
+    const normalized = selected.map(c => { const localCandidateId = `imp_${sha256(`${manifestHash}:${c.candidate.contentHash}:${c.candidate.relativePathHash}`).slice(0, 40)}`; files[localCandidateId] = c.path; return { ...c.candidate, localCandidateId }; });
+    // An empty scan is still a useful report, but cannot be turned into an import plan.
+    const manifest = { schemaVersion: 1, sourceType: inputKind === 'ZIP' ? 'ZIP' : 'DIRECTORY', sourceLabel, candidates: normalized };
+    if (normalized.length)
+        manifestSchema.parse(manifest);
+    checkBytes({ manifest });
+    return { manifest, manifestHash, files, inputKind, unsupported, duplicates, ...(stagingDirectory ? { stagingDirectory } : {}) };
+}

package/dist/skills.d.ts

@@ -0,0 +1,19 @@
+import { execFile } from 'node:child_process';
+export declare const defaultSkillDirectory: () => string;
+export declare function installSkill(directory?: string, stateDir?: string): Promise<{
+    directory: string;
+    cliVersion: string;
+    skillVersion: string;
+}>;
+export declare function updateSkills(stateDir?: string): Promise<{
+    ok: boolean;
+    cliVersion: string;
+    skills: {
+        directory: string;
+        ok: boolean;
+        cliVersion: string;
+        skillVersion?: string;
+        error?: string;
+    }[];
+}>;
+export declare function updatePackage(root?: string, execute?: typeof execFile.__promisify__): Promise<unknown>;

package/dist/skills.js

@@ -0,0 +1,128 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, readdir, mkdir, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { CliError, sha256, VERSION } from './core.js';
+import { checkParents, configDir, privateDirectory, readPrivateJson, writePrivateJson } from './storage.js';
+const run = promisify(execFile);
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const installsSchema = z.array(z.string());
+const markerSchema = z.object({ version: z.string(), hash: z.string() }).strict();
+export const defaultSkillDirectory = () => join(homedir(), '.agents', 'skills', 'family-content');
+export async function installSkill(directory = defaultSkillDirectory(), stateDir = configDir()) {
+    const target = resolve(directory);
+    await checkParents(target);
+    const skill = (await readFile(join(packageRoot, 'skills/family-content/SKILL.md'), 'utf8')).replaceAll('{{CLI_VERSION}}', VERSION);
+    let entries = [];
+    try {
+        entries = await readdir(target);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    if (entries.length) {
+        try {
+            if (entries.some(e => !['SKILL.md', '.yusijia-skill.json'].includes(e)))
+                throw new CliError('SKILL_CONFLICT');
+            const marker = markerSchema.parse(await readPrivateJson(join(target, '.yusijia-skill.json')));
+            await checkParents(join(target, 'SKILL.md'));
+            if (sha256(await readFile(join(target, 'SKILL.md'))) !== marker.hash)
+                throw new CliError('SKILL_CONFLICT');
+        }
+        catch {
+            throw new CliError('SKILL_CONFLICT');
+        }
+    }
+    await privateDirectory(stateDir);
+    const registry = join(stateDir, 'skills.json');
+    let installed = [];
+    try {
+        installed = installsSchema.parse(await readPrivateJson(registry));
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await privateDirectory(target);
+    // Reuse the private atomic writer, then emit plain Markdown rather than JSON.
+    await writeSkillFile(join(target, 'SKILL.md'), skill);
+    await writePrivateJson(join(target, '.yusijia-skill.json'), { version: VERSION, hash: sha256(skill) });
+    await writePrivateJson(registry, [...new Set([...installed, target])]);
+    return { directory: target, cliVersion: VERSION, skillVersion: VERSION };
+}
+async function writeSkillFile(file, text) {
+    const { writePrivateText } = await import('./storage.js');
+    await writePrivateText(file, text);
+}
+export async function updateSkills(stateDir = configDir()) {
+    let installed;
+    try {
+        installed = installsSchema.parse(await readPrivateJson(join(stateDir, 'skills.json')));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { ok: true, cliVersion: VERSION, skills: [] };
+        throw e;
+    }
+    const skills = [];
+    for (const directory of installed) {
+        try {
+            skills.push({ ...(await installSkill(directory, stateDir)), ok: true });
+        }
+        catch {
+            let skillVersion;
+            try {
+                skillVersion = markerSchema.parse(await readPrivateJson(join(directory, '.yusijia-skill.json'))).version;
+            }
+            catch { /* Unknown installations remain untouched. */ }
+            skills.push({ directory, ok: false, cliVersion: VERSION, skillVersion, error: 'SKILL_CONFLICT' });
+        }
+    }
+    return { ok: skills.every(s => s.ok), cliVersion: VERSION, skills };
+}
+export async function updatePackage(root = packageRoot, execute = run) {
+    const manifest = z.object({ name: z.string().regex(/^(?:@[a-z0-9-]+\/)?[a-z0-9-]+$/), version: z.string().regex(/^\d+\.\d+\.\d+(?:-beta\.\d+)?$/), private: z.boolean().optional() }).parse(JSON.parse(await readFile(join(root, 'package.json'), 'utf8')));
+    if (manifest.private)
+        throw new CliError('NOT_PUBLISHED');
+    const channel = manifest.version.includes('-beta.') ? 'beta' : 'latest';
+    let globalRoot;
+    try {
+        globalRoot = (await execute('npm', ['root', '--global'], { timeout: 30000 })).stdout.toString().trim();
+    }
+    catch {
+        throw new CliError('UPDATE_FAILED');
+    }
+    const installedRoot = join(globalRoot, manifest.name);
+    try {
+        if (await realpath(root) !== await realpath(installedRoot))
+            throw new CliError('NOT_GLOBAL');
+    }
+    catch {
+        throw new CliError('NOT_GLOBAL');
+    }
+    try {
+        await execute('npm', ['install', '--global', `${manifest.name}@${channel}`, '--registry=https://registry.npmjs.org/', '--ignore-scripts', '--no-audit', '--no-fund'], { timeout: 300000, maxBuffer: 1024 * 1024 });
+    }
+    catch {
+        throw new CliError('UPDATE_FAILED');
+    }
+    try {
+        const result = await execute(process.execPath, [join(installedRoot, 'dist/cli.js'), 'skills', 'update', '--json'], { timeout: 30000, maxBuffer: 1024 * 1024 });
+        return JSON.parse(result.stdout.toString());
+    }
+    catch (e) {
+        const output = e.stdout;
+        if (output) {
+            try {
+                return JSON.parse(output);
+            }
+            catch { /* Never print npm or subprocess diagnostics. */ }
+        }
+        return { ok: false, cliUpdated: true, error: 'Skill synchronization failed; run yusijia skills update.' };
+    }
+}

package/dist/storage.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const configDir: () => string;
+export declare const MAX_PRIVATE_JSON_BYTES: number;
+export declare function serializePrivateJson(value: unknown): string;
+export declare function checkParents(file: string): Promise<void>;
+export declare function privateDirectory(dir: string): Promise<void>;
+export declare function readPrivateJson(file: string): Promise<unknown>;
+export declare function readInputJson(file: string): Promise<unknown>;
+export declare function writePrivateText(file: string, text: string): Promise<void>;
+export declare function writePrivateJson(file: string, value: unknown): Promise<void>;
+declare const credentialSchema: z.ZodObject<{
+    token: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    userId: z.ZodString;
+}, z.core.$strict>;
+export type Credential = z.infer<typeof credentialSchema>;
+export declare class CredentialStore {
+    readonly directory: string;
+    constructor(directory?: string);
+    private read;
+    get(site: string): Promise<{
+        token: string;
+        expiresAt: string;
+        userId: string;
+    }>;
+    set(site: string, credential: Credential): Promise<void>;
+    remove(site: string): Promise<void>;
+}
+export {};