@series-inc/stowkit-cli 0.1.0

package/dist/cleanup.d.ts

@@ -0,0 +1,3 @@
+export declare function cleanupProject(projectDir: string, opts?: {
+    verbose?: boolean;
+}): Promise<void>;

package/dist/cleanup.js

@@ -0,0 +1,72 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { readProjectConfig, scanDirectory } from './node-fs.js';
+export async function cleanupProject(projectDir, opts) {
+    const verbose = opts?.verbose ?? false;
+    const config = await readProjectConfig(projectDir);
+    const scan = await scanDirectory(config.srcArtDir);
+    // Build set of source files that exist
+    const sourceFiles = new Set(scan.sourceFiles.map(f => f.relativePath));
+    const matFiles = new Set(scan.matFiles.map(f => f.relativePath));
+    let deletedCaches = 0;
+    let deletedMetas = 0;
+    let freedBytes = 0;
+    // Walk all files looking for orphaned .stowcache and .stowmeta
+    await walkForOrphans(config.srcArtDir, '', sourceFiles, matFiles, async (orphanPath, type, size) => {
+        const fullPath = path.join(config.srcArtDir, orphanPath);
+        await fs.unlink(fullPath);
+        freedBytes += size;
+        if (type === 'cache') {
+            deletedCaches++;
+            if (verbose)
+                console.log(`  [delete] ${orphanPath} (orphaned cache)`);
+        }
+        else {
+            deletedMetas++;
+            if (verbose)
+                console.log(`  [delete] ${orphanPath} (orphaned meta)`);
+        }
+    });
+    if (deletedCaches + deletedMetas === 0) {
+        console.log('No orphaned files found.');
+    }
+    else {
+        console.log(`Cleaned up ${deletedCaches} cache(s) and ${deletedMetas} meta(s) (${(freedBytes / 1024).toFixed(0)} KB freed)`);
+    }
+}
+async function walkForOrphans(basePath, prefix, sourceFiles, matFiles, onOrphan) {
+    const dirPath = prefix ? path.join(basePath, prefix) : basePath;
+    let entries;
+    try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (entry.name.startsWith('.'))
+                continue;
+            await walkForOrphans(basePath, relativePath, sourceFiles, matFiles, onOrphan);
+        }
+        else if (entry.isFile()) {
+            if (entry.name.endsWith('.stowcache')) {
+                // Cache orphan: source file doesn't exist
+                const sourceId = relativePath.replace(/\.stowcache$/, '');
+                if (!sourceFiles.has(sourceId) && !matFiles.has(sourceId)) {
+                    const stat = await fs.stat(path.join(basePath, relativePath));
+                    await onOrphan(relativePath, 'cache', stat.size);
+                }
+            }
+            else if (entry.name.endsWith('.stowmeta')) {
+                // Meta orphan: neither source file nor mat file exists
+                const sourceId = relativePath.replace(/\.stowmeta$/, '');
+                if (!sourceFiles.has(sourceId) && !matFiles.has(sourceId)) {
+                    const stat = await fs.stat(path.join(basePath, relativePath));
+                    await onOrphan(relativePath, 'meta', stat.size);
+                }
+            }
+        }
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import * as path from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { fullBuild, scanProject, showStatus } from './orchestrator.js';
+import { startServer } from './server.js';
+import { initProject } from './init.js';
+import { cleanupProject } from './cleanup.js';
+const args = process.argv.slice(2);
+const thisDir = path.dirname(fileURLToPath(import.meta.url));
+const req = createRequire(import.meta.url);
+function printUsage() {
+    console.log(`
+Usage:
+  stowkit init [dir]              Initialize a StowKit project
+  stowkit build [dir]             Full build: scan + process + pack
+  stowkit scan [dir]              Detect new assets, generate .stowmeta defaults
+  stowkit process [dir]           Compress assets (respects cache)
+  stowkit status [dir]            Show project summary, stale asset count
+  stowkit clean [dir]             Delete orphaned .stowcache and .stowmeta files
+  stowkit packer [dir]            Open the packer GUI
+  stowkit editor [dir]            Open the level editor
+  stowkit serve [dir]             Start API server only (no GUI)
+
+Options:
+  --force       Ignore cache and reprocess everything
+  --verbose     Detailed output
+  --port        Server port (default 3210)
+  --help        Show this help message
+`.trim());
+}
+function resolveAppDir(packageName, monorepoFolder) {
+    const candidates = [
+        path.resolve(thisDir, `../../${monorepoFolder}/dist`), // monorepo dev
+    ];
+    try {
+        const pkgJson = req.resolve(`${packageName}/package.json`);
+        candidates.push(path.join(path.dirname(pkgJson), 'dist'));
+    }
+    catch { /* not installed */ }
+    for (const dir of candidates) {
+        if (existsSync(path.join(dir, 'index.html')))
+            return dir;
+    }
+    return null;
+}
+function openBrowser(url) {
+    import('node:child_process').then(({ exec }) => {
+        const cmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+        exec(`${cmd} ${url}`);
+    });
+}
+async function main() {
+    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+        printUsage();
+        process.exit(0);
+    }
+    const command = args[0];
+    const projectDir = args.find(a => !a.startsWith('-') && a !== command) ?? '.';
+    const force = args.includes('--force');
+    const verbose = args.includes('--verbose') || args.includes('-v');
+    const portIdx = args.indexOf('--port');
+    const port = portIdx >= 0 ? parseInt(args[portIdx + 1]) : 3210;
+    const opts = { force, verbose };
+    try {
+        switch (command) {
+            case 'init':
+                await initProject(projectDir);
+                break;
+            case 'build':
+                await fullBuild(projectDir, opts);
+                break;
+            case 'scan': {
+                const report = await scanProject(projectDir, { verbose });
+                console.log(`Project: ${report.projectName}`);
+                console.log(`Source files: ${report.sourceFiles}`);
+                console.log(`Meta files: ${report.metaFiles}`);
+                console.log(`Material files: ${report.matFiles}`);
+                if (report.newFiles.length > 0) {
+                    console.log(`New assets detected (${report.newFiles.length}):`);
+                    for (const f of report.newFiles)
+                        console.log(`  ${f}`);
+                }
+                else {
+                    console.log('No new assets detected.');
+                }
+                break;
+            }
+            case 'process':
+                await fullBuild(projectDir, { ...opts, force });
+                break;
+            case 'status':
+                await showStatus(projectDir);
+                break;
+            case 'clean':
+                await cleanupProject(projectDir, { verbose });
+                break;
+            case 'packer': {
+                const packerDir = resolveAppDir('@series-inc/stowkit-packer-gui', 'stowkit-packer-gui');
+                if (!packerDir) {
+                    console.error('Packer GUI not found. Install it: npm install @series-inc/stowkit-packer-gui');
+                    process.exit(1);
+                }
+                const resolvedProject = path.resolve(projectDir);
+                await startServer({ port, projectDir: resolvedProject, staticApps: { '/': packerDir } });
+                console.log(`\n  Packer: http://localhost:${port}\n`);
+                openBrowser(`http://localhost:${port}`);
+                break;
+            }
+            case 'editor': {
+                const editorDir = resolveAppDir('@series-inc/stowkit-editor', 'stowkit-editor');
+                if (!editorDir) {
+                    console.error('Editor not found. Install it: npm install @series-inc/stowkit-editor');
+                    process.exit(1);
+                }
+                const resolvedProject = path.resolve(projectDir);
+                const packerPort = port + 1;
+                // Start editor server
+                await startServer({ port, projectDir: resolvedProject, staticApps: { '/': editorDir } });
+                // Start packer on next port if installed
+                const packerDir = resolveAppDir('@series-inc/stowkit-packer-gui', 'stowkit-packer-gui');
+                if (packerDir) {
+                    await startServer({ port: packerPort, projectDir: resolvedProject, staticApps: { '/': packerDir } });
+                    console.log(`\n  Editor: http://localhost:${port}`);
+                    console.log(`  Packer: http://localhost:${packerPort}\n`);
+                }
+                else {
+                    console.log(`\n  Editor: http://localhost:${port}\n`);
+                }
+                openBrowser(`http://localhost:${port}`);
+                break;
+            }
+            case 'serve':
+                await startServer({ port, projectDir: projectDir !== '.' ? path.resolve(projectDir) : undefined });
+                break;
+            default:
+                console.error(`Unknown command: ${command}`);
+                printUsage();
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+main();

package/dist/core/binary.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Sequential binary reader over an ArrayBuffer.
+ * All multi-byte reads use little-endian byte order (matching .stow format).
+ */
+export declare class BinaryReader {
+    private readonly view;
+    private pos;
+    constructor(source: ArrayBuffer | Uint8Array, offset?: number);
+    readUint32(): number;
+    readInt32(): number;
+    readUint64(): bigint;
+    readUint64AsNumber(): number;
+    readFloat32(): number;
+    readFixedString(byteLength: number): string;
+    readBytes(length: number): Uint8Array;
+    seek(offset: number): void;
+    tell(): number;
+    get remaining(): number;
+}
+/**
+ * Sequential binary writer into a pre-allocated ArrayBuffer.
+ * All multi-byte writes use little-endian byte order.
+ */
+export declare class BinaryWriter {
+    private readonly buffer;
+    private readonly view;
+    private readonly bytes;
+    private pos;
+    constructor(size: number);
+    writeUint32(value: number): void;
+    writeInt32(value: number): void;
+    writeUint64(value: bigint): void;
+    writeUint64FromNumber(value: number): void;
+    writeFloat32(value: number): void;
+    writeFixedString(value: string, byteLength: number): void;
+    writeBytes(data: Uint8Array): void;
+    seek(offset: number): void;
+    tell(): number;
+    getBuffer(): ArrayBuffer;
+    getUint8Array(): Uint8Array;
+}

package/dist/core/binary.js

@@ -0,0 +1,118 @@
+/**
+ * Sequential binary reader over an ArrayBuffer.
+ * All multi-byte reads use little-endian byte order (matching .stow format).
+ */
+export class BinaryReader {
+    view;
+    pos;
+    constructor(source, offset = 0) {
+        if (source instanceof Uint8Array) {
+            this.view = new DataView(source.buffer, source.byteOffset, source.byteLength);
+        }
+        else {
+            this.view = new DataView(source);
+        }
+        this.pos = offset;
+    }
+    readUint32() {
+        const val = this.view.getUint32(this.pos, true);
+        this.pos += 4;
+        return val;
+    }
+    readInt32() {
+        const val = this.view.getInt32(this.pos, true);
+        this.pos += 4;
+        return val;
+    }
+    readUint64() {
+        const val = this.view.getBigUint64(this.pos, true);
+        this.pos += 8;
+        return val;
+    }
+    readUint64AsNumber() {
+        return Number(this.readUint64());
+    }
+    readFloat32() {
+        const val = this.view.getFloat32(this.pos, true);
+        this.pos += 4;
+        return val;
+    }
+    readFixedString(byteLength) {
+        const bytes = new Uint8Array(this.view.buffer, this.view.byteOffset + this.pos, byteLength);
+        this.pos += byteLength;
+        const nullIdx = bytes.indexOf(0);
+        return new TextDecoder().decode(bytes.subarray(0, nullIdx >= 0 ? nullIdx : byteLength));
+    }
+    readBytes(length) {
+        const bytes = new Uint8Array(this.view.buffer, this.view.byteOffset + this.pos, length);
+        this.pos += length;
+        return bytes.slice();
+    }
+    seek(offset) {
+        this.pos = offset;
+    }
+    tell() {
+        return this.pos;
+    }
+    get remaining() {
+        return this.view.byteLength - this.pos;
+    }
+}
+/**
+ * Sequential binary writer into a pre-allocated ArrayBuffer.
+ * All multi-byte writes use little-endian byte order.
+ */
+export class BinaryWriter {
+    buffer;
+    view;
+    bytes;
+    pos;
+    constructor(size) {
+        this.buffer = new ArrayBuffer(size);
+        this.view = new DataView(this.buffer);
+        this.bytes = new Uint8Array(this.buffer);
+        this.pos = 0;
+    }
+    writeUint32(value) {
+        this.view.setUint32(this.pos, value, true);
+        this.pos += 4;
+    }
+    writeInt32(value) {
+        this.view.setInt32(this.pos, value, true);
+        this.pos += 4;
+    }
+    writeUint64(value) {
+        this.view.setBigUint64(this.pos, value, true);
+        this.pos += 8;
+    }
+    writeUint64FromNumber(value) {
+        this.view.setBigUint64(this.pos, BigInt(value), true);
+        this.pos += 8;
+    }
+    writeFloat32(value) {
+        this.view.setFloat32(this.pos, value, true);
+        this.pos += 4;
+    }
+    writeFixedString(value, byteLength) {
+        const encoded = new TextEncoder().encode(value);
+        this.bytes.fill(0, this.pos, this.pos + byteLength);
+        this.bytes.set(encoded.subarray(0, Math.min(encoded.length, byteLength - 1)), this.pos);
+        this.pos += byteLength;
+    }
+    writeBytes(data) {
+        this.bytes.set(data, this.pos);
+        this.pos += data.length;
+    }
+    seek(offset) {
+        this.pos = offset;
+    }
+    tell() {
+        return this.pos;
+    }
+    getBuffer() {
+        return this.buffer;
+    }
+    getUint8Array() {
+        return this.bytes;
+    }
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,64 @@
+/** Magic number: 'STKT' as little-endian uint32 (0x544B5453) */
+export declare const STOW_MAGIC = 1414222931;
+/** Current format version */
+export declare const STOW_VERSION = 1;
+/** Size of the FileHeader on disk (bytes) */
+export declare const FILE_HEADER_SIZE = 20;
+/** Size of a single AssetDirectoryEntry on disk (bytes) */
+export declare const DIRECTORY_ENTRY_SIZE = 40;
+/** Alignment boundary for data and metadata blobs (bytes) */
+export declare const DATA_ALIGNMENT = 16;
+/** Maximum canonical path length (characters) */
+export declare const MAX_PATH_LENGTH = 512;
+/** Size of the string_id field in metadata structs (bytes) */
+export declare const STRING_ID_SIZE = 128;
+/** Size of TextureMetadata on disk (bytes) */
+export declare const TEXTURE_METADATA_SIZE = 144;
+/** Size of AudioMetadata on disk (bytes) */
+export declare const AUDIO_METADATA_SIZE = 140;
+/** Size of MeshGeometryInfo on disk (bytes) */
+export declare const MESH_GEOMETRY_INFO_SIZE = 40;
+/** Size of SceneNode on disk (bytes) */
+export declare const SCENE_NODE_SIZE = 116;
+/** Size of MaterialData fixed portion on disk (bytes) */
+export declare const MATERIAL_DATA_FIXED_SIZE = 196;
+/** Size of MaterialPropertyValue on disk (bytes) */
+export declare const MATERIAL_PROPERTY_VALUE_SIZE = 144;
+/** Size of MeshMetadata fixed portion on disk (bytes) */
+export declare const MESH_METADATA_FIXED_SIZE = 140;
+/** Node name field size */
+export declare const NODE_NAME_SIZE = 64;
+/** Material name field size */
+export declare const MATERIAL_NAME_SIZE = 64;
+/** Material schema_id field size */
+export declare const MATERIAL_SCHEMA_ID_SIZE = 128;
+/** MaterialPropertyValue field_name / texture_id size */
+export declare const MATERIAL_FIELD_NAME_SIZE = 64;
+/** Material schema_name field size */
+export declare const MATERIAL_SCHEMA_NAME_SIZE = 64;
+/** MaterialSchemaField default_texture_id size */
+export declare const MATERIAL_SCHEMA_DEFAULT_TEXTURE_ID_SIZE = 128;
+/** Size of MaterialSchemaMetadata fixed portion on disk (bytes) */
+export declare const MATERIAL_SCHEMA_METADATA_FIXED_SIZE = 196;
+/** Size of MaterialSchemaField on disk (bytes) */
+export declare const MATERIAL_SCHEMA_FIELD_SIZE = 216;
+/** Bone name field size */
+export declare const BONE_NAME_SIZE = 64;
+/** Size of SkinnedMeshGeometryInfo on disk (bytes) */
+export declare const SKINNED_MESH_GEOMETRY_INFO_SIZE = 72;
+/** Size of SkinnedMeshMetadata fixed portion on disk (bytes) */
+export declare const SKINNED_MESH_METADATA_FIXED_SIZE = 144;
+/** Size of Bone on disk (bytes): name[64] + parent_index(4) + offset_matrix[64] */
+export declare const BONE_SIZE = 132;
+/** Size of VertexWeights on disk (bytes): bone_indices[16] + weights[16] */
+export declare const VERTEX_WEIGHTS_SIZE = 32;
+/** Interleaved vertex size for skinned meshes: pos[3] + normal[3] + uv[2] = 8 floats */
+export declare const SKINNED_VERTEX_STRIDE = 32;
+/** Size of AnimationTrackDescriptor on disk (bytes) */
+export declare const ANIMATION_TRACK_DESCRIPTOR_SIZE = 88;
+/** Size of AnimationClipMetadata fixed portion on disk (bytes) */
+export declare const ANIMATION_CLIP_METADATA_FIXED_SIZE = 268;
+/** Track name field size in AnimationTrackDescriptor */
+export declare const TRACK_NAME_SIZE = 64;
+/** Metadata version discriminator for v2 animation clips */
+export declare const ANIMATION_METADATA_VERSION = 2;

package/dist/core/constants.js

@@ -0,0 +1,65 @@
+/** Magic number: 'STKT' as little-endian uint32 (0x544B5453) */
+export const STOW_MAGIC = 0x544B5453;
+/** Current format version */
+export const STOW_VERSION = 1;
+/** Size of the FileHeader on disk (bytes) */
+export const FILE_HEADER_SIZE = 20;
+/** Size of a single AssetDirectoryEntry on disk (bytes) */
+export const DIRECTORY_ENTRY_SIZE = 40;
+/** Alignment boundary for data and metadata blobs (bytes) */
+export const DATA_ALIGNMENT = 16;
+/** Maximum canonical path length (characters) */
+export const MAX_PATH_LENGTH = 512;
+/** Size of the string_id field in metadata structs (bytes) */
+export const STRING_ID_SIZE = 128;
+/** Size of TextureMetadata on disk (bytes) */
+export const TEXTURE_METADATA_SIZE = 144;
+/** Size of AudioMetadata on disk (bytes) */
+export const AUDIO_METADATA_SIZE = 140;
+/** Size of MeshGeometryInfo on disk (bytes) */
+export const MESH_GEOMETRY_INFO_SIZE = 40;
+/** Size of SceneNode on disk (bytes) */
+export const SCENE_NODE_SIZE = 116;
+/** Size of MaterialData fixed portion on disk (bytes) */
+export const MATERIAL_DATA_FIXED_SIZE = 196;
+/** Size of MaterialPropertyValue on disk (bytes) */
+export const MATERIAL_PROPERTY_VALUE_SIZE = 144;
+/** Size of MeshMetadata fixed portion on disk (bytes) */
+export const MESH_METADATA_FIXED_SIZE = 140;
+/** Node name field size */
+export const NODE_NAME_SIZE = 64;
+/** Material name field size */
+export const MATERIAL_NAME_SIZE = 64;
+/** Material schema_id field size */
+export const MATERIAL_SCHEMA_ID_SIZE = 128;
+/** MaterialPropertyValue field_name / texture_id size */
+export const MATERIAL_FIELD_NAME_SIZE = 64;
+/** Material schema_name field size */
+export const MATERIAL_SCHEMA_NAME_SIZE = 64;
+/** MaterialSchemaField default_texture_id size */
+export const MATERIAL_SCHEMA_DEFAULT_TEXTURE_ID_SIZE = 128;
+/** Size of MaterialSchemaMetadata fixed portion on disk (bytes) */
+export const MATERIAL_SCHEMA_METADATA_FIXED_SIZE = 196;
+/** Size of MaterialSchemaField on disk (bytes) */
+export const MATERIAL_SCHEMA_FIELD_SIZE = 216;
+/** Bone name field size */
+export const BONE_NAME_SIZE = 64;
+/** Size of SkinnedMeshGeometryInfo on disk (bytes) */
+export const SKINNED_MESH_GEOMETRY_INFO_SIZE = 72;
+/** Size of SkinnedMeshMetadata fixed portion on disk (bytes) */
+export const SKINNED_MESH_METADATA_FIXED_SIZE = 144;
+/** Size of Bone on disk (bytes): name[64] + parent_index(4) + offset_matrix[64] */
+export const BONE_SIZE = 132;
+/** Size of VertexWeights on disk (bytes): bone_indices[16] + weights[16] */
+export const VERTEX_WEIGHTS_SIZE = 32;
+/** Interleaved vertex size for skinned meshes: pos[3] + normal[3] + uv[2] = 8 floats */
+export const SKINNED_VERTEX_STRIDE = 32;
+// ─── Animation V2 Constants ─────────────────────────────────────────────────
+/** Size of AnimationTrackDescriptor on disk (bytes) */
+export const ANIMATION_TRACK_DESCRIPTOR_SIZE = 88;
+/** Size of AnimationClipMetadata fixed portion on disk (bytes) */
+export const ANIMATION_CLIP_METADATA_FIXED_SIZE = 268;
+/** Track name field size in AnimationTrackDescriptor */
+export const TRACK_NAME_SIZE = 64;
+/** Metadata version discriminator for v2 animation clips */
+export const ANIMATION_METADATA_VERSION = 2;

package/dist/core/path.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizePath(path: string): string;
+export declare function validatePath(path: string): string | null;
+export declare function djb2Hash(input: string): bigint;

package/dist/core/path.js

@@ -0,0 +1,27 @@
+import { MAX_PATH_LENGTH } from './constants.js';
+export function normalizePath(path) {
+    let result = path.replace(/\\/g, '/');
+    result = result.replace(/\/+/g, '/');
+    result = result.toLowerCase();
+    if (result.length > 1 && result.endsWith('/')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+export function validatePath(path) {
+    if (!path || path.length === 0)
+        return 'Path is empty';
+    if (path.length > MAX_PATH_LENGTH)
+        return `Path exceeds ${MAX_PATH_LENGTH} characters`;
+    return null;
+}
+export function djb2Hash(input) {
+    const normalized = normalizePath(input);
+    let hash = 5381n;
+    for (let i = 0; i < normalized.length; i++) {
+        const c = BigInt(normalized.charCodeAt(i));
+        hash = ((hash << 5n) + hash) + c;
+        hash = hash & 0xffffffffffffffffn;
+    }
+    return hash;
+}