@clunkyard/cli 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clunkyard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# Clunkyard local CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build a robot, play a real local match and inspect its replay with Node 20+,
+npm and your existing language toolchain:
+
+```sh
+npx --yes @clunkyard/cli@2 new javascript my-robot
+cd my-robot
+npx --yes @clunkyard/cli@2 doctor
+npx --yes @clunkyard/cli@2 build
+npx --yes @clunkyard/cli@2 match 42 2d classic
+npx --yes @clunkyard/cli@2 replay
+```
+
+Or clone any [language starter](https://github.com/clunkyard/game-kit) and use
+`make doctor`, `make`, `make match` and `make replay`. A project contains robot
+source, `bot.json` and normal language build metadata. The shared CLI owns the
+tooling; it does not copy a bootstrapper, archive reader or custom lock file
+into every repository. `--project DIRECTORY` works from another directory.
+
+The package contains the reviewed SDK 2.0.0/protocol 2 catalogue, checksums and
+build recipes from the immutable `v2.0.0-kit.2` release. It downloads only the
+engine and selected language SDK. It never downloads compilers or the
+all-language builder. SDK/engine caches under ignored `.clunkyard/` are keyed
+by their content hashes and remain reusable across CLI updates. Other
+commands are `list`, `setup`, `clean` and `migrate`.
+
+JavaScript/TypeScript projects use the ordinary npm alias
+`clunkyard@npm:@clunkyard/sdk@2.0.0`. `package-lock.json` pins the reviewed
+integrity. The first build runs `npm ci --ignore-scripts`; the package has no
+install hooks or runtime dependencies. TypeScript uses your installed
+TypeScript 6+ compiler, preferring a project-local installation. Native SDK
+assets currently require Linux x86-64/glibc 2.39+ (Ubuntu 24.04+ or WSL2).
+JavaScript, TypeScript and the Vane/Cadence/Glyph Node routes use WebAssembly.
+
+`@2` receives compatible tooling updates. For an exact tool version, run
+`npx --yes @clunkyard/cli@2.0.0` or set
+`CLUNKYARD='npx --yes @clunkyard/cli@2.0.0'` with Make. Commit the npm lockfile
+for reproducible JavaScript/TypeScript dependencies. Match replays record the
+game rules and robot actions; local timings do not qualify hosted budgets.
+
+For an older generated kit checkout, commit your work and run
+`npx --yes @clunkyard/cli@2 migrate`. It removes only byte-recognized generated
+helper files, preserves robot source and custom README text, and refuses to
+overwrite customized build scripts or dependency manifests. Historical kit
+archives remain available with their original tooling.
+
+Robot builds and local matches execute programs as your user. Use trusted
+source and tools. For online play, use
+[`@clunkyard/git`](https://www.npmjs.com/package/@clunkyard/git) or Clunkyard's
+GitHub integration, then run hosted trials before entering a tournament.
+
+[SDK and adapters](https://clunkyard.com/sdk) ·
+[Local trials](https://clunkyard.com/sdk/local-trials) ·
+[Private Git](https://clunkyard.com/sdk/private-git)

package/archive.cjs

@@ -0,0 +1,74 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const crypto = require('node:crypto');
+
+async function readAsset(asset) {
+  let bytes;
+  if(process.env.CLUNKYARD_RELEASE_DIRECTORY)bytes=fs.readFileSync(path.join(process.env.CLUNKYARD_RELEASE_DIRECTORY,asset.file));
+  else {
+    const response=await fetch(asset.url,{signal:AbortSignal.timeout(120000)});
+    if(!response.ok)throw new Error(`Download failed (${response.status}): ${asset.url}`);
+    const chunks=[];let size=0;
+    for await(const chunk of response.body){size+=chunk.length;if(size>asset.bytes)throw new Error('Release download exceeds its recorded size');chunks.push(chunk);}
+    bytes=Buffer.concat(chunks,size);
+  }
+  if(bytes.length!==asset.bytes||crypto.createHash('sha256').update(bytes).digest('hex')!==asset.sha256)throw new Error(`Release checksum mismatch: ${asset.file}`);
+  return bytes;
+}
+
+// Release archives contain ordinary files and directories only. They never
+// carry checkout hooks, symlinks or absolute paths.
+function archive(root) {
+  const parts = [];
+  function visit(directory, relative = '') {
+    for (const item of fs.readdirSync(directory, { withFileTypes:true }).sort((a,b) => a.name.localeCompare(b.name))) {
+      const name = relative ? `${relative}/${item.name}` : item.name;
+      const file = path.join(directory, item.name), stat = fs.statSync(file);
+      if (stat.isDirectory()) { visit(file, name); continue; }
+      if (!stat.isFile()) throw new Error(`Unsupported release file: ${name}`);
+      const data = fs.readFileSync(file), header = Buffer.alloc(512);
+      const slash = name.lastIndexOf('/'), leaf = name.length > 100 ? name.slice(slash + 1) : name, prefix = name.length > 100 ? name.slice(0, slash) : '';
+      if (Buffer.byteLength(leaf) > 100 || Buffer.byteLength(prefix) > 155) throw new Error(`Release path too long: ${name}`);
+      header.write(leaf, 0, 100); header.write(`${(stat.mode & 0o111 ? 0o755 : 0o644).toString(8).padStart(7,'0')}\0`, 100);
+      header.write('0000000\0',108); header.write('0000000\0',116);
+      header.write(`${data.length.toString(8).padStart(11,'0')}\0`,124); header.write('00000000000\0',136);
+      header.fill(32,148,156); header[156]=48; header.write('ustar\0',257); header.write('00',263); header.write(prefix,345,155);
+      const checksum = [...header].reduce((n,b) => n+b,0); header.write(`${checksum.toString(8).padStart(6,'0')}\0 `,148);
+      parts.push(header,data,Buffer.alloc((512-data.length%512)%512));
+    }
+  }
+  visit(root); parts.push(Buffer.alloc(1024)); return zlib.gzipSync(Buffer.concat(parts), { level:9 });
+}
+
+function extract(bytes, root, maxBytes = 256 * 1024 * 1024) {
+  const data = zlib.gunzipSync(bytes, { maxOutputLength:maxBytes });
+  let cursor = 0, count = 0;
+  while (cursor + 512 <= data.length) {
+    const header = data.subarray(cursor,cursor+512); cursor += 512;
+    if (header.every(byte => byte===0)) return;
+    const text = (start,end) => header.subarray(start,end).toString('utf8').replace(/\0.*$/s,'');
+    const leaf = text(0,100), prefix = text(345,500), name = prefix ? `${prefix}/${leaf}` : leaf;
+    if (++count > 10000 || !name || name.includes('\\') || name.split('/').some(part => !part || part==='.' || part==='..' || part.toLowerCase()==='.git') || path.isAbsolute(name)) throw new Error('Unsafe release archive path');
+    if (![0,48].includes(header[156])) throw new Error('Release archive contains a link or unsupported object');
+    const expected = parseInt(text(148,156).trim(),8), copy = Buffer.from(header); copy.fill(32,148,156);
+    if (expected !== [...copy].reduce((n,b) => n+b,0)) throw new Error('Release archive header failed verification');
+    const size = parseInt(text(124,136).trim(),8);
+    if (!Number.isSafeInteger(size) || size < 0 || cursor+size > data.length) throw new Error('Invalid release archive size');
+    let parent = root;
+    for (const part of name.split('/').slice(0,-1)) {
+      parent = path.join(parent,part);
+      if (fs.existsSync(parent) && (!fs.lstatSync(parent).isDirectory() || fs.lstatSync(parent).isSymbolicLink())) throw new Error('Unsafe release directory');
+      fs.mkdirSync(parent,{recursive:true});
+    }
+    const file = path.join(root,...name.split('/'));
+    if (fs.existsSync(file)) throw new Error('Release archive repeats an existing path');
+    fs.writeFileSync(file,data.subarray(cursor,cursor+size),{mode:parseInt(text(100,108),8)&0o111?0o755:0o644,flag:'wx'});
+    cursor += Math.ceil(size/512)*512;
+  }
+  throw new Error('Incomplete release archive');
+}
+
+module.exports = { archive, extract, readAsset };