@peekling/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,569 @@
+import { adaptCodexPetV2, } from "@peekling/adapter-codex-pet";
+import { parseDataText, parseManifestText, validateNativePack, } from "@peekling/runtime/pack";
+import { lstat, mkdir, open, realpath, readdir, rm, writeFile, } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { PNG } from "pngjs";
+import { atomicDirectory } from "./atomic-directory.js";
+import { inspectImage } from "./image.js";
+import { createFixtureAtlas } from "./png.js";
+import { readZipEntries } from "./zip.js";
+const EXECUTABLE = /\.(?:js|mjs|cjs|ts|tsx|jsx|html?|wasm|sh|bat|cmd|exe|dll|dylib|so|jar|py|rb|php)$/i;
+function decodeJsonUtf8(bytes, label) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new Error(`${label} must be valid UTF-8`, { cause });
+    }
+}
+function starterManifest(name, sha256) {
+    const directions = ["N", "NE", "E", "SE", "W", "SW", "NW", "S"];
+    const states = {
+        idle: { frames: [0, 1], fps: 2, loop: true },
+    };
+    directions.forEach((direction, index) => {
+        states[`move:${direction}`] = {
+            frames: [16 + index * 2, 17 + index * 2],
+            fps: 6,
+            loop: true,
+        };
+    });
+    [
+        "click",
+        "double-click",
+        "context-click",
+        "scroll",
+        "happy",
+        "success",
+        "error",
+        "sleep",
+    ].forEach((state, index) => {
+        states[state] = {
+            frames: [32 + index * 2, 33 + index * 2],
+            fps: 4,
+            loop: state === "sleep",
+        };
+    });
+    return {
+        format: 1,
+        name,
+        version: "0.1.0",
+        license: "CC0-1.0",
+        metadata: {
+            title: `${name} development fixture`,
+            author: "Generated by the Peekling CLI",
+            description: "Synthetic geometric placeholder. Replace before release.",
+            tags: ["development-fixture"],
+        },
+        assets: {
+            atlas: {
+                src: "atlas.png",
+                sha256,
+                columns: 16,
+                rows: 3,
+                logicalCellSize: 32,
+                sourceCellSize: 32,
+                density: 1,
+            },
+        },
+        states,
+        capabilities: {
+            locomotion: {
+                directions: Object.fromEntries(directions.map((direction) => [direction, `move:${direction}`])),
+            },
+        },
+        defaults: { scale: 2 },
+    };
+}
+export async function packAuthoringSource(sourceDirectory, output) {
+    const sourceRoot = await realpath(path.resolve(sourceDirectory));
+    const sourceText = (await readBoundedFile(await confinedSourceFile(sourceRoot, "source.json", "source.json"), 64 * 1024, "source.json")).toString("utf8");
+    const raw = parseDataText(sourceText, "source.json");
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("source.json must be an object");
+    const author = raw;
+    const name = author.name;
+    const version = author.version;
+    const license = author.license;
+    const logicalCellSize = author.logicalCellSize;
+    if (typeof name !== "string" ||
+        !/^[a-z][a-z0-9-]{0,63}$/.test(name) ||
+        typeof version !== "string" ||
+        !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version) ||
+        typeof license !== "string" ||
+        ![32, 64].includes(logicalCellSize))
+        throw new Error("source.json identity or logicalCellSize is invalid");
+    if (!Array.isArray(author.sources) ||
+        author.sources.length < 1 ||
+        author.sources.length > 3)
+        throw new Error("source.json requires 1 through 3 density sources");
+    const sources = author.sources;
+    const seenDensity = new Set();
+    for (const source of sources) {
+        if (![1, 2, 4].includes(source.density) ||
+            seenDensity.has(source.density) ||
+            Boolean(source.sheet) === Boolean(source.directory))
+            throw new Error("Each source density must be unique and use sheet or directory");
+        seenDensity.add(source.density);
+        const sourcePath = source.sheet ?? source.directory;
+        validateSourcePath(sourcePath, `${source.density}x source`);
+        if (source.sheet &&
+            (!Number.isInteger(source.columns) ||
+                !Number.isInteger(source.rows) ||
+                source.columns < 1 ||
+                source.columns > 64 ||
+                source.rows < 1 ||
+                source.rows > 64)) {
+            throw new Error("Source sheet columns and rows must be integers 1-64");
+        }
+    }
+    if (!author.states ||
+        typeof author.states !== "object" ||
+        Array.isArray(author.states))
+        throw new Error("source.json states must be an object");
+    const stateEntries = Object.entries(author.states);
+    if (stateEntries.length < 1 || stateEntries.length > 64)
+        throw new Error("source.json states must contain 1 through 64 entries");
+    const names = [];
+    const packedIndex = new Map();
+    for (const [stateName, state] of stateEntries) {
+        if (!/^[a-z][a-z0-9-]*(?::(?:N|NE|E|SE|S|SW|W|NW|[a-z0-9-]+))?$/.test(stateName))
+            throw new Error(`Invalid source state name: ${stateName}`);
+        if (!Array.isArray(state.frames) ||
+            !state.frames.length ||
+            state.frames.length > 64 ||
+            state.frames.some((frame) => !/^[a-z][a-z0-9-]{0,63}$/.test(frame)))
+            throw new Error(`${stateName}.frames must contain safe stable names`);
+        if ((state.fps === undefined) === (state.durations === undefined))
+            throw new Error(`${stateName} must declare exactly one of fps or durations`);
+        for (const frame of state.frames)
+            if (!packedIndex.has(frame)) {
+                packedIndex.set(frame, names.length);
+                names.push(frame);
+            }
+    }
+    if (names.length > 64)
+        throw new Error("source.json exceeds 64 unique frames");
+    const rows = Math.max(2, Math.ceil(names.length / 16));
+    for (const source of sources) {
+        const cell = logicalCellSize * source.density;
+        if (16 * cell > 4_096 || rows * cell > 4_096)
+            throw new Error("Compiled atlas would exceed 4096x4096 pixels");
+        if (source.sheet &&
+            Number(source.columns) * cell * (Number(source.rows) * cell) * 4 >
+                64 * 1024 * 1024) {
+            throw new Error("Decoded source allocation exceeds 64 MiB");
+        }
+    }
+    const compiledStates = Object.fromEntries(stateEntries.map(([stateName, state]) => [
+        stateName,
+        {
+            frames: state.frames.map((frame) => packedIndex.get(frame)),
+            loop: state.loop,
+            ...(state.fps === undefined ? {} : { fps: state.fps }),
+            ...(state.durations === undefined
+                ? {}
+                : { durations: state.durations }),
+        },
+    ]));
+    const frameLocations = new Map();
+    for (const [, state] of stateEntries) {
+        if (state.row === undefined)
+            continue;
+        if (!Number.isInteger(state.row) || state.row < 0)
+            throw new Error("Source rows must be non-negative integers");
+        const seenInState = new Set();
+        state.frames.forEach((frame, column) => {
+            if (seenInState.has(frame))
+                return;
+            seenInState.add(frame);
+            const existing = frameLocations.get(frame);
+            const next = { row: state.row, column };
+            if (existing &&
+                (existing.row !== next.row || existing.column !== next.column))
+                throw new Error(`Named frame ${frame} has conflicting source locations`);
+            frameLocations.set(frame, next);
+        });
+    }
+    for (const source of sources) {
+        if (!source.sheet)
+            continue;
+        for (const [frame, location] of frameLocations) {
+            if (location.row >= Number(source.rows) ||
+                location.column >= Number(source.columns)) {
+                throw new Error(`Named frame ${frame} source location is outside ${source.density}x sheet geometry`);
+            }
+        }
+    }
+    await atomicDirectory(output, async (temp) => {
+        const variants = [];
+        let compiledBytes = 0;
+        for (const source of [...sources].sort((a, b) => a.density - b.density)) {
+            const cell = logicalCellSize * source.density;
+            const outputWidth = 16 * cell;
+            const outputHeight = rows * cell;
+            if (outputWidth * outputHeight * 4 > 64 * 1024 * 1024)
+                throw new Error("Compiled atlas allocation exceeds 64 MiB");
+            const atlas = new PNG({ width: outputWidth, height: outputHeight });
+            let sheet;
+            if (source.sheet) {
+                const sourceFile = await confinedSourceFile(sourceRoot, source.sheet, `${source.density}x source sheet`);
+                const bytes = await readBoundedFile(sourceFile, 32 * 1024 * 1024, `${source.density}x source sheet`);
+                const header = inspectImage(bytes, source.sheet);
+                if (header.mimeType !== "image/png" ||
+                    header.width !== Number(source.columns) * cell ||
+                    header.height !== Number(source.rows) * cell)
+                    throw new Error(`${source.density}x source sheet geometry is invalid`);
+                sheet = PNG.sync.read(bytes);
+            }
+            for (const [frameName, index] of packedIndex) {
+                let frame;
+                if (sheet) {
+                    const location = frameLocations.get(frameName);
+                    if (!location)
+                        throw new Error(`Named frame ${frameName} lacks a source row`);
+                    frame = cropPng(sheet, location.column * cell, location.row * cell, cell);
+                }
+                else {
+                    const relative = path.posix.join(source.directory.replaceAll("\\", "/"), `${frameName}.png`);
+                    const file = await confinedSourceFile(sourceRoot, relative, frameName);
+                    const frameBytes = await readBoundedFile(file, 4 * 1024 * 1024, frameName);
+                    const header = inspectImage(frameBytes, file);
+                    if (header.mimeType !== "image/png" ||
+                        header.width !== cell ||
+                        header.height !== cell)
+                        throw new Error(`${frameName} must be exactly ${cell}x${cell}`);
+                    frame = PNG.sync.read(frameBytes);
+                }
+                blitPng(frame, atlas, (index % 16) * cell, Math.floor(index / 16) * cell);
+            }
+            const bytes = PNG.sync.write(atlas, {
+                colorType: 6,
+                deflateLevel: 9,
+                filterType: 4,
+            });
+            if (bytes.length > 4 * 1024 * 1024)
+                throw new Error(`${source.density}x compiled atlas exceeds 4 MiB`);
+            compiledBytes += bytes.length;
+            if (compiledBytes > 8 * 1024 * 1024)
+                throw new Error("Compiled atlas variants exceed 8 MiB total");
+            const fileName = `atlas-${source.density}x.png`;
+            await writeFile(path.join(temp, fileName), bytes);
+            variants.push({
+                src: fileName,
+                density: source.density,
+                sourceCellSize: cell,
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+            });
+        }
+        const manifest = {
+            format: 1,
+            name,
+            version,
+            license,
+            ...(author.metadata ? { metadata: author.metadata } : {}),
+            assets: {
+                atlases: {
+                    columns: 16,
+                    rows,
+                    logicalCellSize,
+                    lineage: typeof author.lineage === "string"
+                        ? author.lineage
+                        : `${name}-compiled-v1`,
+                    variants,
+                },
+            },
+            states: compiledStates,
+            ...(author.capabilities === undefined
+                ? {}
+                : { capabilities: author.capabilities }),
+            defaults: { scale: author.scale ?? (logicalCellSize === 64 ? 1 : 2) },
+        };
+        await writeFile(path.join(temp, "character.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        for (const required of ["LICENSE", "PROVENANCE.md"])
+            await writeFile(path.join(temp, required), await readBoundedFile(await confinedSourceFile(sourceRoot, required, required), 256 * 1024, required));
+        await validatePackDirectory(temp);
+    });
+}
+function validateSourcePath(relative, label) {
+    if (typeof relative !== "string" ||
+        relative.length < 1 ||
+        relative.length > 256 ||
+        path.isAbsolute(relative) ||
+        relative.includes("\\") ||
+        relative.split("/").some((part) => !part || part === "." || part === "..")) {
+        throw new Error(`${label} must be a confined relative path`);
+    }
+}
+async function confinedSourceFile(sourceRoot, relative, label) {
+    validateSourcePath(relative, label);
+    const target = await realpath(path.join(sourceRoot, relative)).catch(() => {
+        throw new Error(`Missing required ${label}`);
+    });
+    const relation = path.relative(sourceRoot, target);
+    if (relation.startsWith("..") || path.isAbsolute(relation))
+        throw new Error(`${label} escapes the source directory`);
+    return target;
+}
+function cropPng(input, x0, y0, size) {
+    const output = new PNG({ width: size, height: size });
+    for (let y = 0; y < size; y++) {
+        const source = ((y0 + y) * input.width + x0) * 4;
+        input.data.copy(output.data, y * size * 4, source, source + size * 4);
+    }
+    return output;
+}
+function blitPng(source, target, x0, y0) {
+    for (let y = 0; y < source.height; y++) {
+        const from = y * source.width * 4;
+        const to = ((y0 + y) * target.width + x0) * 4;
+        source.data.copy(target.data, to, from, from + source.width * 4);
+    }
+}
+export async function createPack(target, name) {
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
+        throw new Error("Pack name must be lowercase letters, numbers, and hyphens");
+    }
+    await atomicDirectory(target, async (temp) => {
+        const atlas = createFixtureAtlas();
+        const manifest = starterManifest(name, createHash("sha256").update(atlas).digest("hex"));
+        await writeFile(path.join(temp, "character.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        await writeFile(path.join(temp, "atlas.png"), atlas);
+        await writeFile(path.join(temp, "LICENSE"), "CC0 1.0 Universal\n\nThe synthetic geometric fixture in atlas.png is dedicated to the public domain. Replace it and this license before distributing different art.\n");
+        await writeFile(path.join(temp, "PROVENANCE.md"), "# Development fixture provenance\n\n`atlas.png` was generated algorithmically by `@peekling/cli`. It contains no downloaded or third-party character art and is a development placeholder, not release character art.\n");
+    });
+}
+async function scanPack(root) {
+    const rootInfo = await lstat(root).catch(() => {
+        throw new Error(`Pack directory does not exist: ${root}`);
+    });
+    if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory())
+        throw new Error(`Pack path must be a real directory, not a link: ${root}`);
+    let files = 0;
+    let bytes = 0;
+    let directories = 0;
+    async function visit(directory, depth) {
+        if (depth > 8)
+            throw new Error("Pack exceeds directory-depth limit");
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const absolute = path.join(directory, entry.name);
+            const relative = path.relative(root, absolute);
+            const info = await lstat(absolute);
+            if (info.isSymbolicLink())
+                throw new Error(`Pack must not contain symbolic links: ${relative}`);
+            if (info.isDirectory()) {
+                directories++;
+                if (directories > 64)
+                    throw new Error("Pack exceeds directory-count limit");
+                await visit(absolute, depth + 1);
+            }
+            else if (info.isFile()) {
+                files++;
+                bytes += info.size;
+                if (files > 32 || bytes > 8 * 1024 * 1024)
+                    throw new Error("Pack exceeds file-count or total-size limits");
+                if (EXECUTABLE.test(entry.name))
+                    throw new Error(`Pack contains executable content: ${relative}`);
+            }
+        }
+    }
+    await visit(root, 0);
+}
+async function readBoundedFile(target, limit, label) {
+    const value = await readMaybeBoundedFile(target, limit, label, false);
+    if (!value)
+        throw new Error(`Missing required ${label}: ${target}`);
+    return value;
+}
+async function readOptionalBoundedFile(target, limit, label) {
+    return readMaybeBoundedFile(target, limit, label, true);
+}
+async function readMaybeBoundedFile(target, limit, label, optional) {
+    let initial;
+    try {
+        initial = await lstat(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            if (optional)
+                return undefined;
+            throw new Error(`Missing required ${label}: ${target}`);
+        }
+        throw error;
+    }
+    if (initial.isSymbolicLink() || !initial.isFile()) {
+        throw new Error(`${label} must be a regular file, not a link: ${target}`);
+    }
+    if (initial.size > limit)
+        throw new Error(`${label} exceeds ${limit} bytes`);
+    const handle = await open(target, "r").catch((error) => {
+        if (error.code === "ENOENT") {
+            throw new Error(`${label} changed before it could be read`);
+        }
+        throw error;
+    });
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() ||
+            opened.dev !== initial.dev ||
+            opened.ino !== initial.ino) {
+            throw new Error(`${label} changed before it could be read`);
+        }
+        if (opened.size > limit)
+            throw new Error(`${label} exceeds ${limit} bytes`);
+        const bytes = Buffer.alloc(Math.min(limit + 1, opened.size + 1));
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const result = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+            if (result.bytesRead === 0)
+                break;
+            offset += result.bytesRead;
+        }
+        const after = await handle.stat();
+        if (after.size !== opened.size || after.mtimeMs !== opened.mtimeMs) {
+            throw new Error(`${label} changed while it was being read`);
+        }
+        if (offset > limit)
+            throw new Error(`${label} exceeds ${limit} bytes`);
+        return bytes.subarray(0, offset);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function validatePackDirectory(target) {
+    const root = path.resolve(target);
+    await scanPack(root);
+    const manifestPath = path.join(root, "character.json");
+    const manifestText = (await readBoundedFile(manifestPath, 64 * 1024, "manifest")).toString("utf8");
+    const raw = parseManifestText(manifestText);
+    const preliminary = validateNativePack(raw);
+    const variants = preliminary.atlas.variants ?? [
+        {
+            src: preliminary.atlas.src,
+            density: preliminary.atlas.density ?? 1,
+            cellWidth: preliminary.atlas.cellWidth,
+            cellHeight: preliminary.atlas.cellHeight,
+            sha256: preliminary.atlas.sha256,
+        },
+    ];
+    let pack = preliminary;
+    let totalBytes = 0;
+    let largest = { width: 0, height: 0, bytes: 0 };
+    for (const variant of variants) {
+        const atlasPath = path.resolve(root, variant.src);
+        if (!atlasPath.startsWith(`${root}${path.sep}`))
+            throw new Error("Atlas path escapes the pack root");
+        const atlas = await readBoundedFile(atlasPath, 4 * 1024 * 1024, `declared ${variant.density}x atlas`);
+        const image = inspectImage(atlas, variant.src);
+        if (image.mimeType !== "image/png")
+            throw new Error("Native v0.1 atlas variants must be PNG");
+        if (!image.hasAlpha)
+            throw new Error(`Native ${variant.density}x atlas requires alpha`);
+        if (createHash("sha256").update(atlas).digest("hex") !== variant.sha256)
+            throw new Error(`Native ${variant.density}x atlas SHA-256 does not match`);
+        pack = validateNativePack(raw, {
+            width: image.width,
+            height: image.height,
+            byteLength: atlas.length,
+        }, variant.density);
+        totalBytes += atlas.length;
+        if (image.width * image.height > largest.width * largest.height)
+            largest = {
+                width: image.width,
+                height: image.height,
+                bytes: atlas.length,
+            };
+    }
+    if (totalBytes > 8 * 1024 * 1024)
+        throw new Error("Native atlas variants exceed the 8 MiB pack limit");
+    const license = (await readOptionalBoundedFile(path.join(root, "LICENSE"), 256 * 1024, "LICENSE"))?.toString("utf8");
+    if (!license?.trim())
+        throw new Error("Pack requires a non-empty LICENSE file");
+    return {
+        name: pack.name,
+        version: pack.version,
+        atlas: largest,
+        states: Object.keys(pack.states).length,
+    };
+}
+async function codexSource(input) {
+    const info = await lstat(input);
+    if (info.isDirectory()) {
+        const pet = await readBoundedFile(path.join(input, "pet.json"), 64 * 1024, "pet.json");
+        let atlasName = "spritesheet.webp";
+        let atlas = await readOptionalBoundedFile(path.join(input, atlasName), 32 * 1024 * 1024, atlasName);
+        if (!atlas) {
+            atlasName = "spritesheet.png";
+            atlas = await readBoundedFile(path.join(input, atlasName), 32 * 1024 * 1024, atlasName);
+        }
+        const license = await readOptionalBoundedFile(path.join(input, "LICENSE"), 256 * 1024, "LICENSE");
+        return { pet, atlas, atlasName, ...(license ? { license } : {}) };
+    }
+    if (!input.endsWith(".codex-pet"))
+        throw new Error("Codex input must be a directory or .codex-pet archive");
+    if (info.isSymbolicLink() || !info.isFile())
+        throw new Error("Codex input must be a regular directory or archive");
+    const archive = await readBoundedFile(input, 40 * 1024 * 1024, ".codex-pet archive");
+    const entries = readZipEntries(archive);
+    const pet = entries.get("pet.json");
+    const atlasName = entries.has("spritesheet.webp")
+        ? "spritesheet.webp"
+        : "spritesheet.png";
+    const atlas = entries.get(atlasName);
+    if (!pet || !atlas)
+        throw new Error(".codex-pet must contain root pet.json and spritesheet.webp");
+    const license = entries.get("LICENSE");
+    return { pet, atlas, atlasName, archive, ...(license ? { license } : {}) };
+}
+export async function importCodexPet(input, output, metadata) {
+    for (const [field, value] of Object.entries(metadata)) {
+        if (field !== "allowPng" &&
+            (typeof value !== "string" || value.trim() === "")) {
+            throw new Error(`Codex import requires --${field}`);
+        }
+    }
+    const source = await codexSource(path.resolve(input));
+    if (source.atlasName === "spritesheet.png" && !metadata.allowPng) {
+        throw new Error("PNG compatibility input requires --allow-png and must be self-hosted");
+    }
+    const pet = parseDataText(decodeJsonUtf8(source.pet, "pet.json"), "pet.json");
+    const image = inspectImage(source.atlas, source.atlasName);
+    const sidecar = {
+        format: 1,
+        adapter: "codex-pet-v2",
+        license: metadata.license,
+        provenance: {
+            author: metadata.author,
+            source: metadata.source,
+            rights: metadata.rights,
+        },
+    };
+    adaptCodexPetV2({
+        pet,
+        sidecar,
+        atlas: {
+            fileName: source.atlasName,
+            width: image.width,
+            height: image.height,
+            mimeType: image.mimeType,
+            hasAlpha: image.hasAlpha,
+            sha256: createHash("sha256").update(source.atlas).digest("hex"),
+            byteLength: source.atlas.length,
+        },
+        ...(metadata.allowPng ? { allowSelfHostedPng: true } : {}),
+    });
+    await atomicDirectory(output, async (temp) => {
+        await writeFile(path.join(temp, "pet.json"), source.pet);
+        await writeFile(path.join(temp, source.atlasName), source.atlas);
+        await writeFile(path.join(temp, "peekling.json"), `${JSON.stringify(sidecar, null, 2)}\n`);
+        if (source.license)
+            await writeFile(path.join(temp, "LICENSE"), source.license);
+        else
+            await writeFile(path.join(temp, "LICENSE"), `${metadata.license}\n`);
+        if (source.archive)
+            await writeFile(path.join(temp, "source.codex-pet"), source.archive);
+    });
+}
+export { createFixtureAtlas } from "./png.js";

package/dist/png.d.ts

@@ -0,0 +1,7 @@
+export declare function createFixtureAtlas(rows?: number): Buffer;
+export declare function inspectPng(buffer: Buffer): {
+    width: number;
+    height: number;
+    hasAlpha: boolean;
+};
+//# sourceMappingURL=png.d.ts.map

package/dist/png.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png.d.ts","sourceRoot":"","sources":["../src/png.ts"],"names":[],"mappings":"AA0CA,wBAAgB,kBAAkB,CAAC,IAAI,SAAI,GAAG,MAAM,CA8CnD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CACnB,CA2DA"}