@clunkyard/git 0.0.0-stage → 2.0.2

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,44 @@
-# Temporary Holding Version
+# Private Clunkyard Git
 
-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.
+Requires Node 20 or later and Git. Install the reviewed release with `npm install --global @clunkyard/git@2.0.1`;
+no language toolchain is added. A downloaded release tarball can also be installed
+with `npm install --global ./clunkyard-git-2.0.1.tgz`. On Linux/macOS, add
+`--prefix "$HOME/.local"` and put `$HOME/.local/bin` on PATH for a user-owned install.
+
+This package provides command-line tools; it has no supported JavaScript module API.
+
+Create an **agent access key** on your Clunkyard Account page, then run:
+
+```sh
+clunkyard-git login
+git clone clunkyard::https://clunkyard.com/bots/BOT_ID my-robot
+cd my-robot
+# Edit your robot, then use ordinary Git.
+git add bot.vane
+git commit -m "Improve target selection"
+git push origin main
+```
+
+The key is entered without echo and stored in your user configuration directory.
+Keep that directory outside your repository, including when overriding
+`XDG_CONFIG_HOME` or `APPDATA`. An agent key acts for your account; revoke it from the
+Account page when no longer needed. It never goes in the remote URL or project.
+For a secret-manager pipeline, `clunkyard-git login --token-stdin` also works.
+
+The initial clone starts ordinary Git history at your current saved project.
+Older application revisions remain in Clunkyard's revision history. Subsequent
+browser and WebDAV saves become commits on the same `main` branch. Use `git
+fetch`, inspect the change and merge before pushing stale work. Only `main` is
+supported; force pushes, branch creation, tags, submodules and symlinks are not.
+Push at most 32 new commits at once, within the project's file and source limits.
+
+Binary files and executable bits are retained. Git does not represent empty
+directories or arbitrary Unix permission bits; existing empty directories and
+non-executable permissions remain application metadata. Historical project
+`.git` files are never checked out or executed and remain private application
+history. A push cannot replace them.
+
+Successful pushes publish an immutable source revision and request its normal
+hosted build. Compilation may fail independently; inspect the build in My bots.
+An interrupted push retains an operation receipt inside your local Git directory;
+retry `git push` to reconcile it without duplicating a saved revision.

package/client.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function credentialPath() {
+  const root = process.platform === 'win32' ? process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming') : process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  if (!path.isAbsolute(root)) throw Error('The Clunkyard configuration directory must be absolute.');
+  return path.join(root, 'clunkyard', 'credentials.json');
+}
+function origin(value) {
+  const url = new URL(value);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/' || url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw Error('Use an HTTPS Clunkyard origin, without a path or credentials.');
+  return url.origin;
+}
+function readCredentials() {
+  const file = credentialPath();
+  let stat; try { stat = fs.lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return {}; throw Error('Cannot read Clunkyard credentials.'); }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536 || process.platform !== 'win32' && (stat.mode & 0o077 || stat.uid !== process.getuid())) throw Error('Clunkyard credentials must be a private, owner-only file.');
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error('Invalid Clunkyard credentials.');
+  return value;
+}
+function saveCredential(site, key) {
+  site = origin(site);
+  if (typeof key !== 'string' || !key || /\s/.test(key) || key.length > 1024) throw Error('Invalid Clunkyard access key.');
+  const file = credentialPath(), directory = path.dirname(file), credentials = readCredentials();
+  fs.mkdirSync(directory, { recursive:true, mode:0o700 });
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || process.platform !== 'win32' && (stat.mode & 0o077 || stat.uid !== process.getuid())) throw Error('Clunkyard credentials need a private configuration directory.');
+  credentials[site] = key;
+  const temporary = path.join(directory, `.credentials-${require('node:crypto').randomUUID()}`);
+  try { fs.writeFileSync(temporary, JSON.stringify(credentials) + '\n', { mode:0o600, flag:'wx' }); fs.renameSync(temporary, file); }
+  finally { fs.rmSync(temporary, { force:true }); }
+  return file;
+}
+function keyFor(site) {
+  // An environment key is scoped too: a hostile Git remote must not receive
+  // the player's production credential merely because it is in the shell.
+  if (process.env.CLUNKYARD_AGENT_KEY && site === origin(process.env.CLUNKYARD_ORIGIN || 'https://clunkyard.com')) return process.env.CLUNKYARD_AGENT_KEY;
+  const key = readCredentials()[site];
+  if (!key) throw Error(`Sign in first with clunkyard-git login --origin ${site}`);
+  return key;
+}
+async function readJson(response, limit = 40 * 1024 * 1024) {
+  const reader = response.body?.getReader(), chunks = []; let size = 0;
+  if (!reader) throw Error('Clunkyard returned an empty response.');
+  for (;;) { const { done, value } = await reader.read(); if (done) break; size += value.length; if (size > limit) { await reader.cancel(); throw Error('Clunkyard response exceeds the client limit.'); } chunks.push(Buffer.from(value)); }
+  let result; try { result = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw Error('Clunkyard returned an invalid response.'); }
+  if (!response.ok) throw Object.assign(Error(typeof result.error === 'string' ? result.error.slice(0, 240) : `Clunkyard request failed (${response.status}).`), { status:response.status });
+  return result;
+}
+async function request(site, route, { method = 'GET', body, operationId, key = keyFor(site) } = {}) {
+  const response = await fetch(site + route, { method, redirect:'error', signal:AbortSignal.timeout(45000), headers:{ Authorization:`Bearer ${key}`, Accept:'application/json', ...(body === undefined ? {} : { 'Content-Type':'application/json' }), ...(operationId ? { 'X-Clunkyard-Request':operationId } : {}) }, ...(body === undefined ? {} : { body:JSON.stringify(body) }) });
+  return readJson(response);
+}
+
+module.exports = { credentialPath, origin, readCredentials, saveCredential, keyFor, request };

package/git-remote-clunkyard

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { origin, request } = require('./client.cjs');
+
+const OID = /^[0-9a-f]{40}$/;
+function git(args, options = {}) { return execFileSync('git', ['-c', 'core.hooksPath=', ...args], { stdio:['pipe', 'pipe', 'pipe'], maxBuffer:40 * 1024 * 1024, ...options }); }
+function objectId(type, data) { return crypto.createHash('sha1').update(`${type} ${data.length}\0`).update(data).digest('hex'); }
+function objectRefs(value) {
+  if (value.type === 'blob') return [];
+  if (value.type === 'commit') { const end = value.data.indexOf('\n\n'); return value.data.subarray(0, end).toString('utf8').split('\n').filter(line => /^(tree|parent) /.test(line)).map(line => line.split(' ')[1]); }
+  const ids = []; let offset = 0;
+  while (offset < value.data.length) { const nul = value.data.indexOf(0, offset); if (nul < 0 || nul + 21 > value.data.length) throw Error('Invalid Git tree received.'); ids.push(value.data.subarray(nul + 1, nul + 21).toString('hex')); offset = nul + 21; }
+  return ids;
+}
+const raw = process.argv[3];
+let url;
+try { url = new URL(String(raw).replace(/^clunkyard::/, '')); } catch { throw Error('Use clunkyard::https://clunkyard.com/bots/BOT_ID'); }
+if (url.username || url.password || url.search || url.hash || !/^\/bots\/[0-9a-f-]{36}$/.test(url.pathname)) throw Error('Invalid private bot remote.');
+const site = origin(url.origin), botId = url.pathname.split('/').at(-1), route = `/api/bots/${botId}/git`;
+const ask = (suffix = '', options) => request(site, route + suffix, options);
+let advertised;
+const say = text => process.stdout.write(text + '\n');
+const cleanError = error => String(error.message || 'Private Git operation failed.').replace(/[\r\n]/g, ' ').slice(0, 240);
+
+async function fetchObjects(ids) {
+  const visited = new Set(), queue = [...ids];
+  while (queue.length) {
+    const batch = [...new Set(queue.splice(0, 128))].filter(id => !visited.has(id));
+    if (!batch.length) continue;
+    for (const id of batch) if (!OID.test(id)) throw Error('Invalid Git object requested.');
+    const answer = await ask('/objects', { method:'POST', body:{ oids:batch } });
+    for (const wire of answer.objects || []) {
+      if (!batch.includes(wire.oid) || !['blob', 'tree', 'commit'].includes(wire.type) || typeof wire.data !== 'string') throw Error('Invalid Git object received.');
+      const data = Buffer.from(wire.data, 'base64');
+      if (data.toString('base64') !== wire.data || objectId(wire.type, data) !== wire.oid) throw Error('Git object failed verification.');
+      const actual = git(['hash-object', '-w', '-t', wire.type, '--stdin'], { input:data }).toString().trim();
+      if (actual !== wire.oid) throw Error('Git rejected an object.');
+      visited.add(wire.oid); queue.push(...objectRefs({ ...wire, data }));
+    }
+    if (!Array.isArray(answer.objects) || !answer.objects.length) throw Error('Missing Git objects in response.');
+    queue.push(...(answer.remaining || []));
+  }
+}
+function localObjects(head, base, maxCommits) {
+  const commits = git(['rev-list', `--max-count=${maxCommits + 1}`, head, `^${base}`]).toString().trim().split('\n').filter(Boolean);
+  if (commits.length > maxCommits) throw Error(`Push at most ${maxCommits} commits at a time.`);
+  const ids = git(['rev-list', '--objects', head, `^${base}`]).toString().split('\n').filter(Boolean).map(line => line.slice(0, 40));
+  if (ids.some(id => !OID.test(id))) throw Error('Cannot list the local Git objects.');
+  const data = git(['cat-file', '--batch'], { input:ids.join('\n') + '\n' }), objects = []; let offset = 0;
+  for (const expected of ids) {
+    const newline = data.indexOf(10, offset), line = data.subarray(offset, newline).toString('ascii'), parsed = line.match(/^([0-9a-f]{40}) (blob|tree|commit) ([0-9]+)$/);
+    if (!parsed || parsed[1] !== expected) throw Error('Cannot read a local Git object.');
+    const size = Number(parsed[3]), bytes = data.subarray(newline + 1, newline + 1 + size);
+    if (bytes.length !== size || data[newline + 1 + size] !== 10) throw Error('Invalid local Git object size.');
+    objects.push({ oid:expected, type:parsed[2], data:bytes.toString('base64') }); offset = newline + size + 2;
+  }
+  return objects;
+}
+function pushReceipt(head, base) {
+  const directory = git(['rev-parse', '--absolute-git-dir']).toString().trim(), file = path.join(directory, 'clunkyard-push.json');
+  let receipt; try { const stat = fs.lstatSync(file); if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) throw Error('Invalid private Git push receipt.'); receipt = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (!receipt || receipt.site !== site || receipt.botId !== botId || receipt.head !== head || receipt.base !== base) {
+    receipt = { site, botId, head, base, operationId:crypto.randomUUID() };
+    fs.writeFileSync(file, JSON.stringify(receipt) + '\n', { mode:0o600, flag:'w' });
+  }
+  return { receipt, clear:() => fs.rmSync(file, { force:true }) };
+}
+async function waitForPush(value) {
+  for (let attempt = 0; value.state === 'pending' && attempt < 10; attempt++) {
+    await new Promise(resolve => setTimeout(resolve, 500));
+    value = await ask(`/push/${value.operationId}`, { method:'POST' });
+  }
+  return value;
+}
+async function push(spec) {
+  let target = spec.split(':').at(-1);
+  try {
+    const match = spec.match(/^([^:]+):(refs\/heads\/main)$/);
+    if (!match || spec.startsWith('+')) throw Error('Only fast-forward pushes to main are supported; branches, tags and deletion are unavailable.');
+    target = match[2]; let state = await ask();
+    if (state.pending) { const settled = await waitForPush(await ask(`/push/${state.pending.operationId}`, { method:'POST' })); if (settled.state === 'pending') throw Error(`An earlier push is still resolving (${state.pending.operationId}). Retry later.`); state = await ask(); }
+    const head = git(['rev-parse', '--verify', `${match[1]}^{commit}`]).toString().trim();
+    try { git(['merge-base', '--is-ancestor', state.head, head]); } catch { throw Error('The remote branch changed. Fetch and merge before pushing.'); }
+    if (head === state.head) { say(`ok ${target}`); return; }
+    const objects = localObjects(head, state.head, state.limits.maxCommits), journal = pushReceipt(head, state.head);
+    let result;
+    try { result = await waitForPush(await ask('/push', { method:'POST', body:{ base:state.head, head, objects }, operationId:journal.receipt.operationId })); }
+    catch (error) {
+      // A lost response is not proof of failure. Ask the durable operation,
+      // retaining the same ID until the server confirms its outcome.
+      try { result = await waitForPush(await ask(`/push/${journal.receipt.operationId}`, { method:'POST' })); } catch { throw error; }
+    }
+    if (result.state === 'not-saved') { journal.clear(); throw Error('The interrupted push was cancelled before sending. Retry git push.'); }
+    if (result.state !== 'committed' || result.head !== head) throw Error(`Push still resolving (${journal.receipt.operationId}). Retry git push to reconcile it.`);
+    journal.clear(); say(`ok ${target}`);
+  } catch (error) { say(`error ${target || 'refs/heads/main'} ${cleanError(error)}`); }
+}
+
+(async () => {
+  const input = readline.createInterface({ input:process.stdin, crlfDelay:Infinity }), lines = input[Symbol.asyncIterator]();
+  for await (const line of lines) {
+    if (line === 'capabilities') { say('fetch'); say('push'); say('option'); say(''); }
+    else if (line.startsWith('option ')) say('unsupported');
+    else if (line === 'list' || line === 'list for-push') { advertised = await ask(); say('@refs/heads/main HEAD'); say(`${advertised.head} refs/heads/main`); say(''); }
+    else if (line.startsWith('fetch ')) {
+      const batch = [line]; for (;;) { const next = await lines.next(); if (next.done || !next.value) break; batch.push(next.value); }
+      await fetchObjects(batch.map(value => value.split(' ')[1])); say('');
+    } else if (line.startsWith('push ')) {
+      const batch = [line]; for (;;) { const next = await lines.next(); if (next.done || !next.value) break; batch.push(next.value); }
+      if (batch.length !== 1) { for (const item of batch) say(`error ${item.split(':').at(-1)} Push one main branch at a time.`); }
+      else await push(batch[0].slice(5)); say('');
+    } else if (!line) break;
+    else throw Error('Unsupported private Git helper command.');
+  }
+})().catch(error => { process.stderr.write(`Clunkyard: ${cleanError(error)}\n`); process.exitCode = 1; process.stdin.destroy(); });

package/login.cjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+
+const { origin, saveCredential, request } = require('./client.cjs');
+
+async function secret() {
+  if (!process.stdin.isTTY) {
+    let input = ''; for await (const data of process.stdin) { input += data; if (input.length > 2048) throw Error('Access key is too long.'); }
+    return input.trim();
+  }
+  process.stderr.write('Agent access key (hidden): ');
+  process.stdin.setRawMode(true); process.stdin.resume(); process.stdin.setEncoding('utf8');
+  return new Promise((resolve, reject) => {
+    let value = '';
+    const finish = error => { process.stdin.removeListener('data', receive); process.stdin.setRawMode(false); process.stdin.pause(); process.stderr.write('\n'); error ? reject(error) : resolve(value); };
+    function receive(data) { for (const character of data) { if (character === '\u0003') return finish(Error('Sign-in cancelled.')); if (character === '\r' || character === '\n') return finish(); if (character === '\u007f' || character === '\b') value = value.slice(0, -1); else value += character; if (value.length > 1024) return finish(Error('Access key is too long.')); } }
+    process.stdin.on('data', receive);
+  });
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.shift() !== 'login') throw Error('Usage: clunkyard-git login [--origin https://clunkyard.com] [--token-stdin]');
+  let site = 'https://clunkyard.com';
+  while (args.length) { const flag = args.shift(); if (flag === '--origin') site = args.shift(); else if (flag !== '--token-stdin') throw Error('Unknown sign-in option.'); }
+  site = origin(site); const key = await secret();
+  const me = await request(site, '/api/me', { key });
+  if (!me.account?.handle) throw Error('This access key does not identify a player.');
+  const file = saveCredential(site, key);
+  process.stdout.write(`Signed in as @${me.account.handle}. Credentials saved at ${file}.\n`);
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@clunkyard/git",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.2",
+  "description": "Ordinary private Git for Clunkyard bot projects",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "git-remote-clunkyard": "git-remote-clunkyard",
+    "clunkyard-git": "login.cjs"
+  },
+  "files": [
+    "git-remote-clunkyard",
+    "login.cjs",
+    "client.cjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clunkyard/sdk.git",
+    "directory": "packages/git"
+  },
+  "homepage": "https://clunkyard.com/sdk/private-git",
+  "bugs": {
+    "url": "https://github.com/clunkyard/sdk/issues"
+  },
+  "keywords": [
+    "clunkyard",
+    "git",
+    "robot",
+    "arena"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  }
+}