@cogineai/dearharness 0.1.0 → 0.1.1

package/README.md

@@ -8,65 +8,88 @@ It is derived from `cogine-ai/cliq-agent`, but it is not a generic coding agent.
 
 This repository is a standalone prototype. The main DearClaw platform repository may later consume or import stable pieces from it.
 
-V0 scope:
+The current public npm package is `@cogineai/dearharness@0.1.0`.
+
+Implemented baseline:
 
 - local CLI identity
 - OpenClaw workspace inspection
 - install-lock status reading
 - local Harness manifest validation
 - minimal private daemon task API
+- remote `.zip` and `.tar.gz` bundle source staging
+- dry-run install planning and conflict reporting
+- guarded file apply with rollback and post-apply verification
+- daemon `install_harness` tasks that use the same guarded install runner as the CLI
 
-V1 work has started with remote `.zip` and `.tar.gz` bundle source staging, dry-run install planning, conflict reporting, guarded file apply, and post-apply verification. DearHarness still does not claim full OpenClaw config mutation, publication, package signing, dependency solving, or OpenClaw plugin installation.
+DearHarness still does not claim full OpenClaw config mutation, DearStore registry or publish API integration, package signing, dependency solving, or OpenClaw plugin installation.
 
 ## Quick Start
 
 Requirements: Node.js 20 or newer.
 
+Run the published CLI without installing it globally:
+
+```bash
+npx -y @cogineai/dearharness help
+```
+
+Or install it globally:
+
+```bash
+npm install -g @cogineai/dearharness
+dearharness help
+```
+
+For local source development:
+
 ```bash
 npm install
 npm run build
 node dist/index.js help
 ```
 
+The examples below use the installed `dearharness` binary. In a source checkout, replace `dearharness` with `node dist/index.js`.
+
 Inspect an OpenClaw-like workspace:
 
 ```bash
-node dist/index.js inspect --target-workspace ~/.openclaw/workspace
+dearharness inspect --target-workspace ~/.openclaw/workspace
 ```
 
 Read local install status:
 
 ```bash
-node dist/index.js status --target-workspace ~/.openclaw/workspace
+dearharness status --target-workspace ~/.openclaw/workspace
 ```
 
 Validate a Harness source directory:
 
 ```bash
-node dist/index.js validate ./my-harness
+dearharness validate ./my-harness
 ```
 
 Download and validate a remote Harness bundle without applying changes. The install runner accepts either a `.zip` or `.tar.gz` archive URL:
 
 ```bash
-node dist/index.js install https://example.com/my-harness.zip --target-workspace ~/.openclaw/workspace --dry-run
-node dist/index.js install https://example.com/my-harness.tar.gz --target-workspace ~/.openclaw/workspace --dry-run
+dearharness install https://example.com/my-harness.zip --target-workspace ~/.openclaw/workspace --dry-run
+dearharness install https://example.com/my-harness.tar.gz --target-workspace ~/.openclaw/workspace --dry-run
 ```
 
 Apply a conflict-free plan explicitly:
 
 ```bash
-node dist/index.js install https://example.com/my-harness.zip --target-workspace ~/.openclaw/workspace --apply
-node dist/index.js install https://example.com/my-harness.tar.gz --target-workspace ~/.openclaw/workspace --apply
+dearharness install https://example.com/my-harness.zip --target-workspace ~/.openclaw/workspace --apply
+dearharness install https://example.com/my-harness.tar.gz --target-workspace ~/.openclaw/workspace --apply
 ```
 
-Run the V0 daemon:
+Run the private daemon:
 
 ```bash
-DEARHARNESS_DAEMON_TOKEN=dev-token node dist/index.js daemon --host 127.0.0.1 --port 18790
+DEARHARNESS_DAEMON_TOKEN=dev-token dearharness daemon --host 127.0.0.1 --port 18790
 ```
 
-Submit a V0 daemon task:
+Submit an inspect task:
 
 ```bash
 curl -sS \
@@ -121,7 +144,7 @@ If DearHarness needs a generally useful runtime capability, prefer opening an up
 
 Extensions are intentionally limited to hooks and instruction contributions. They do not register new model-callable top-level actions.
 
-## V0 Task Types
+## Daemon Task Types
 
 The daemon currently accepts synchronous task requests:
 

package/dist/harness/source.js

@@ -2,11 +2,22 @@ import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { gunzipSync, unzipSync } from 'fflate';
+import { gunzipSync, inflateRawSync } from 'node:zlib';
 import { validateHarnessSource } from './manifest.js';
 const DEFAULT_MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_DECOMPRESSED_BYTES = DEFAULT_MAX_ARCHIVE_BYTES;
 const MANIFEST_FILE = 'dearharness.manifest.json';
 const TAR_BLOCK_SIZE = 512;
+const ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
+const ZIP_CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50;
+const ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50;
+const ZIP_MAX_END_OF_CENTRAL_DIRECTORY_SEARCH = 65_558;
+const ZIP_GENERAL_PURPOSE_ENCRYPTED = 0x1;
+const ZIP_COMPRESSION_STORED = 0;
+const ZIP_COMPRESSION_DEFLATE = 8;
+const ZIP_UINT32_MAX = 0xffffffff;
+const ZIP_UINT16_MAX = 0xffff;
+const CRC32_TABLE = buildCrc32Table();
 function detectSourceKind(input) {
     let url;
     try {
@@ -59,14 +70,176 @@ function safeArchiveEntryPath(root, entryName) {
     }
     return target;
 }
-async function extractZipToStaging(archive, stagingPath) {
-    const entries = unzipSync(archive);
-    for (const [entryName, data] of Object.entries(entries)) {
+function decompressedSizeLimitError(maxDecompressedBytes) {
+    return new Error(`harness source archive exceeds ${maxDecompressedBytes} bytes when decompressed`);
+}
+function buildCrc32Table() {
+    const table = new Uint32Array(256);
+    for (let index = 0; index < table.length; index++) {
+        let value = index;
+        for (let bit = 0; bit < 8; bit++) {
+            value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+        }
+        table[index] = value >>> 0;
+    }
+    return table;
+}
+function crc32(data) {
+    let value = 0xffffffff;
+    for (const byte of data) {
+        value = CRC32_TABLE[(value ^ byte) & 0xff] ^ (value >>> 8);
+    }
+    return (value ^ 0xffffffff) >>> 0;
+}
+function invalidZipError(message) {
+    return new Error(`invalid harness source zip archive: ${message}`);
+}
+function findZipEndOfCentralDirectory(archive) {
+    for (let offset = archive.byteLength - 22; offset >= 0 && archive.byteLength - offset <= ZIP_MAX_END_OF_CENTRAL_DIRECTORY_SEARCH; offset--) {
+        if (archive.readUInt32LE(offset) === ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE) {
+            return offset;
+        }
+    }
+    throw invalidZipError('missing end of central directory');
+}
+function parseZipCentralDirectory(archive) {
+    const directoryEnd = findZipEndOfCentralDirectory(archive);
+    const diskNumber = archive.readUInt16LE(directoryEnd + 4);
+    const centralDirectoryDisk = archive.readUInt16LE(directoryEnd + 6);
+    const entriesOnDisk = archive.readUInt16LE(directoryEnd + 8);
+    const entryCount = archive.readUInt16LE(directoryEnd + 10);
+    const centralDirectorySize = archive.readUInt32LE(directoryEnd + 12);
+    const centralDirectoryOffset = archive.readUInt32LE(directoryEnd + 16);
+    if (diskNumber !== 0 || centralDirectoryDisk !== 0 || entriesOnDisk !== entryCount) {
+        throw invalidZipError('multi-disk zip archives are not supported');
+    }
+    if (entryCount === ZIP_UINT16_MAX ||
+        centralDirectorySize === ZIP_UINT32_MAX ||
+        centralDirectoryOffset === ZIP_UINT32_MAX) {
+        throw invalidZipError('Zip64 archives are not supported');
+    }
+    if (centralDirectoryOffset + centralDirectorySize > archive.byteLength) {
+        throw invalidZipError('central directory exceeds archive bounds');
+    }
+    const entries = [];
+    let offset = centralDirectoryOffset;
+    const centralDirectoryEnd = centralDirectoryOffset + centralDirectorySize;
+    for (let index = 0; index < entryCount; index++) {
+        if (offset + 46 > centralDirectoryEnd || archive.readUInt32LE(offset) !== ZIP_CENTRAL_DIRECTORY_SIGNATURE) {
+            throw invalidZipError('malformed central directory entry');
+        }
+        const flags = archive.readUInt16LE(offset + 8);
+        const compressionMethod = archive.readUInt16LE(offset + 10);
+        const entryCrc32 = archive.readUInt32LE(offset + 16);
+        const compressedSize = archive.readUInt32LE(offset + 20);
+        const uncompressedSize = archive.readUInt32LE(offset + 24);
+        const nameLength = archive.readUInt16LE(offset + 28);
+        const extraLength = archive.readUInt16LE(offset + 30);
+        const commentLength = archive.readUInt16LE(offset + 32);
+        const localHeaderOffset = archive.readUInt32LE(offset + 42);
+        const entryEnd = offset + 46 + nameLength + extraLength + commentLength;
+        if (entryEnd > centralDirectoryEnd) {
+            throw invalidZipError('central directory entry exceeds archive bounds');
+        }
+        if (compressedSize === ZIP_UINT32_MAX ||
+            uncompressedSize === ZIP_UINT32_MAX ||
+            localHeaderOffset === ZIP_UINT32_MAX) {
+            throw invalidZipError('Zip64 entries are not supported');
+        }
+        const name = archive.subarray(offset + 46, offset + 46 + nameLength).toString('utf8');
+        entries.push({
+            name,
+            flags,
+            compressionMethod,
+            crc32: entryCrc32,
+            compressedSize,
+            uncompressedSize,
+            localHeaderOffset,
+        });
+        offset = entryEnd;
+    }
+    if (offset !== centralDirectoryEnd) {
+        throw invalidZipError('central directory has trailing bytes');
+    }
+    return entries;
+}
+function zipEntryCompressedData(archive, entry) {
+    const headerOffset = entry.localHeaderOffset;
+    if (headerOffset + 30 > archive.byteLength ||
+        archive.readUInt32LE(headerOffset) !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) {
+        throw invalidZipError(`missing local file header for ${entry.name}`);
+    }
+    const localFlags = archive.readUInt16LE(headerOffset + 6);
+    const localCompressionMethod = archive.readUInt16LE(headerOffset + 8);
+    const nameLength = archive.readUInt16LE(headerOffset + 26);
+    const extraLength = archive.readUInt16LE(headerOffset + 28);
+    const dataStart = headerOffset + 30 + nameLength + extraLength;
+    const dataEnd = dataStart + entry.compressedSize;
+    if (localCompressionMethod !== entry.compressionMethod) {
+        throw invalidZipError(`zip entry compression method mismatch: ${entry.name}`);
+    }
+    if ((localFlags & ZIP_GENERAL_PURPOSE_ENCRYPTED) !== 0 || (entry.flags & ZIP_GENERAL_PURPOSE_ENCRYPTED) !== 0) {
+        throw invalidZipError(`encrypted zip entries are not supported: ${entry.name}`);
+    }
+    if (dataStart > archive.byteLength || dataEnd > archive.byteLength) {
+        throw invalidZipError(`zip entry data exceeds archive bounds: ${entry.name}`);
+    }
+    return archive.subarray(dataStart, dataEnd);
+}
+function extractZipEntryData(entry, compressed, remainingBudget, maxDecompressedBytes) {
+    if (entry.compressionMethod === ZIP_COMPRESSION_STORED) {
+        if (entry.compressedSize !== entry.uncompressedSize) {
+            throw new Error(`zip entry size mismatch: ${entry.name}`);
+        }
+        return Buffer.from(compressed);
+    }
+    if (entry.compressionMethod !== ZIP_COMPRESSION_DEFLATE) {
+        throw invalidZipError(`unsupported zip entry compression method ${entry.compressionMethod}: ${entry.name}`);
+    }
+    try {
+        return inflateRawSync(compressed, { maxOutputLength: remainingBudget });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ERR_BUFFER_TOO_LARGE') {
+            throw decompressedSizeLimitError(maxDecompressedBytes);
+        }
+        throw new Error(`failed to decompress harness source zip entry ${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function extractZipToStaging(archive, stagingPath, maxDecompressedBytes) {
+    let extractedTotal = 0;
+    for (const entry of parseZipCentralDirectory(archive)) {
+        const entryName = entry.name;
         const target = safeArchiveEntryPath(stagingPath, entryName);
-        if (entryName.replace(/\\/g, '/').endsWith('/')) {
+        const normalizedName = entryName.replace(/\\/g, '/');
+        if (entry.uncompressedSize > maxDecompressedBytes - extractedTotal) {
+            throw decompressedSizeLimitError(maxDecompressedBytes);
+        }
+        if (normalizedName.endsWith('/')) {
+            const compressed = zipEntryCompressedData(archive, entry);
+            const data = extractZipEntryData(entry, compressed, maxDecompressedBytes - extractedTotal, maxDecompressedBytes);
+            if (data.byteLength !== 0 || entry.uncompressedSize !== 0) {
+                throw new Error(`zip entry size mismatch: ${entry.name}`);
+            }
+            if (crc32(data) !== entry.crc32) {
+                throw new Error(`zip entry crc mismatch: ${entry.name}`);
+            }
             await fs.mkdir(target, { recursive: true });
             continue;
         }
+        const compressed = zipEntryCompressedData(archive, entry);
+        const data = extractZipEntryData(entry, compressed, maxDecompressedBytes - extractedTotal, maxDecompressedBytes);
+        if (data.byteLength !== entry.uncompressedSize) {
+            throw new Error(`zip entry size mismatch: ${entry.name}`);
+        }
+        if (crc32(data) !== entry.crc32) {
+            throw new Error(`zip entry crc mismatch: ${entry.name}`);
+        }
+        extractedTotal += data.byteLength;
+        if (extractedTotal > maxDecompressedBytes) {
+            throw decompressedSizeLimitError(maxDecompressedBytes);
+        }
         await fs.mkdir(path.dirname(target), { recursive: true });
         await fs.writeFile(target, data);
     }
@@ -142,15 +315,18 @@ function parseTarEntries(archive) {
     }
     return entries;
 }
-async function extractTarGzToStaging(archive, stagingPath) {
-    let inflated;
+async function extractTarGzToStaging(archive, stagingPath, maxDecompressedBytes) {
+    let tarBuffer;
     try {
-        inflated = gunzipSync(archive);
+        tarBuffer = gunzipSync(archive, { maxOutputLength: maxDecompressedBytes });
     }
     catch (error) {
+        const code = error.code;
+        if (code === 'ERR_BUFFER_TOO_LARGE') {
+            throw decompressedSizeLimitError(maxDecompressedBytes);
+        }
         throw new Error(`failed to decompress harness source gzip stream: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const tarBuffer = Buffer.from(inflated);
     const entries = parseTarEntries(tarBuffer);
     for (const entry of entries) {
         const target = safeArchiveEntryPath(stagingPath, entry.name);
@@ -197,11 +373,12 @@ export async function materializeHarnessSource(input, options = {}) {
         if (options.expectedSha256 && options.expectedSha256.toLowerCase() !== sha256) {
             throw new Error(`harness source sha256 mismatch: expected ${options.expectedSha256}, got ${sha256}`);
         }
+        const maxDecompressedBytes = options.maxDecompressedBytes ?? DEFAULT_MAX_DECOMPRESSED_BYTES;
         if (kind === 'zip-url') {
-            await extractZipToStaging(archive, stagingPath);
+            await extractZipToStaging(archive, stagingPath, maxDecompressedBytes);
         }
         else {
-            await extractTarGzToStaging(archive, stagingPath);
+            await extractTarGzToStaging(archive, stagingPath, maxDecompressedBytes);
         }
         const rootPath = await findHarnessRoot(stagingPath);
         const validation = await validateHarnessSource(rootPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogineai/dearharness",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "OpenClaw Harness operator CLI and instance-side daemon prototype.",
   "type": "module",
   "license": "MIT",
@@ -36,7 +36,9 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepack": "npm run build",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "test": "node --test --import tsx \"src/**/*.test.ts\""

package/dist/model/openrouter.js

@@ -1,9 +0,0 @@
-import { DEFAULT_MODEL_CONFIG } from './registry.js';
-import { createOpenRouterClient as createOpenRouterProviderClient } from './providers/openrouter.js';
-export function createOpenRouterClient(config) {
-    const resolved = config ?? {
-        ...DEFAULT_MODEL_CONFIG,
-        apiKey: process.env.OPENROUTER_API_KEY
-    };
-    return createOpenRouterProviderClient(resolved);
-}