cadet-agent 0.4.0

package/README.md

@@ -0,0 +1,71 @@
+# Cadet-Agent
+
+Cadet-Agent is a cross-IDE agent framework for game-development workflows, with a shared framework core and authored root integrations for GitHub Copilot, Cursor, Continue, and Claude Code.
+
+## Repository Layout
+- `.cadet/agent/core/` contains the shared Cadet-Agent framework documents.
+- `.cadet/agent/docs/` contains setup guides for each supported IDE.
+- `AGENTS.md` contains shared top-level agent instructions.
+- `.github/` contains GitHub Copilot-specific authored files.
+- `.cursor/` contains Cursor-specific authored files.
+- `.continue/` contains Continue-specific authored files.
+- `.claude/` contains Claude Code-specific authored files.
+- `package-agent.ps1` builds the distributable `cadet-agent.zip` package.
+
+## Getting Started
+- For repository setup and package contents, see [.cadet/agent/README.md](.cadet/agent/README.md).
+- For framework navigation, see [.cadet/agent/core/README.md](.cadet/agent/core/README.md).
+- For GitHub Copilot setup, see [.cadet/agent/docs/github-copilot.md](.cadet/agent/docs/github-copilot.md).
+- For Cursor setup, see [.cadet/agent/docs/cursor.md](.cadet/agent/docs/cursor.md).
+- For Continue setup, see [.cadet/agent/docs/continue.md](.cadet/agent/docs/continue.md).
+- For Claude Code setup, see [.cadet/agent/docs/claude-code.md](.cadet/agent/docs/claude-code.md).
+
+## Examples
+
+### GitHub Copilot kickoff
+After extracting `cadet-agent.zip` into a game repository, open the repo in VS Code and start a kickoff chat using the Cadet prompt.
+
+```text
+/cadet Help me bootstrap a beginner-friendly 2D racing prototype in Unity with AI opponents and a career progression loop.
+```
+
+Cadet-Agent will use `.github/prompts/cadet.prompt.md` plus the shared framework in `.cadet/agent/core` to route the conversation through learner calibration, bootstrap checks, and planning.
+
+### Cursor feature request
+After opening the repository in Cursor, the always-apply rule in `.cursor/rules/cadet-agent.md` should load automatically. A typical request looks like this:
+
+```text
+Design a small vertical slice for a kart handling prototype in Unity. Start with requirements, then a technical design, then the first TDD task.
+```
+
+Cursor will use the Cadet rule to pull workflow, standards, and guidance from `.cadet/agent/core` before responding.
+
+### Continue planning request
+With Continue installed in VS Code, open the repository and ask for a scoped planning artifact:
+
+```text
+Create a requirements outline for a single-player time-trial mode with ghost replay support and Given/When/Then acceptance criteria.
+```
+
+The Continue rule in `.continue/rules/cadet-agent.md` should steer the response back through the shared Cadet framework.
+
+### Repository policy example
+If a specific game repository needs local conventions, add a policy file under `.cadet/agent/policies` using `.cadet/agent/core/Templates/PolicyTemplate.md`. For example, a repository policy could define:
+- where project plans should live
+- where shared gameplay code should be extracted
+- which Unity packages or UI stack are the project default
+
+## Package Output
+Running `./package-agent.ps1` produces `cadet-agent.zip` with this layout:
+- `.cadet/agent/core/`
+- `AGENTS.md`
+- `.github/cadet-copilot-instructions.md`
+- `.github/prompts/cadet.prompt.md`
+- `.cursor/rules/cadet-agent.md`
+- `.continue/rules/cadet-agent.md`
+- `.claude/skills/cadet-agent.md`
+
+## Notes
+- `.cadet/agent/core/FrameworkManifest.json` defines the managed and preserved paths for packaged installs.
+- Repository-specific policy overlays belong in `.cadet/agent/policies`.
+- Planning artifacts belong in `.cadet/agent/project-plans` unless an active policy says otherwise.

package/bin/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.mjs';
+
+run(process.argv).catch((err) => {
+  console.error('\n❌ Unexpected error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "cadet-agent",
+  "version": "0.4.0",
+  "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
+  "type": "module",
+  "bin": {
+    "cadet-agent": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "cadet",
+    "cadet-agent",
+    "unity",
+    "game-development",
+    "ai-agent",
+    "copilot",
+    "cursor",
+    "claude-code"
+  ],
+  "license": "CC-BY-4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naishtech/cadet-agent.git"
+  },
+  "homepage": "https://github.com/naishtech/cadet-agent#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { install } from './install.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getVersion() {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+  return pkg.version;
+}
+
+function showHelp() {
+  console.log(`
+  ██████╗ █████╗ ██████╗ ███████╗████████╗
+  ██╔════╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
+  ██║     ███████║██║  ██║█████╗     ██║
+  ██║     ██╔══██║██║  ██║██╔══╝     ██║
+  ╚██████╗██║  ██║██████╔╝███████╗   ██║
+   ╚═════╝╚═╝  ╚═╝╚═════╝ ╚══════╝   ╚═╝
+
+  Cross-IDE agent framework for Unity/C# game-development
+
+  Usage:
+    npx cadet-agent@latest init     Install Cadet-Agent into the current directory
+    npx cadet-agent@latest init --target <dir>   Install into a specific directory
+
+  Options:
+    --target, -t  Target directory (default: current working directory)
+    --help, -h    Show this help
+    --version, -v Show version number
+`);
+}
+
+export async function run(argv) {
+  const command = argv[2];
+
+  // Parse --target <dir> or -t <dir>
+  let targetDir = process.cwd();
+  const targetIdx = argv.indexOf('--target');
+  const tIdx = argv.indexOf('-t');
+  if (targetIdx !== -1 && argv[targetIdx + 1]) {
+    targetDir = argv[targetIdx + 1];
+  } else if (tIdx !== -1 && argv[tIdx + 1]) {
+    targetDir = argv[tIdx + 1];
+  }
+
+  switch (command) {
+    case 'init':
+      await install(targetDir);
+      break;
+    case '--version':
+    case '-v':
+      console.log(`cadet-agent v${getVersion()}`);
+      break;
+    case '--help':
+    case '-h':
+    case undefined:
+      showHelp();
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.error('Run cadet-agent --help for usage.');
+      process.exit(1);
+  }
+}

package/src/install.mjs

@@ -0,0 +1,205 @@
+import { createWriteStream, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { inflateRawSync } from 'node:zlib';
+import { tmpdir } from 'node:os';
+import { Readable } from 'node:stream';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const GITHUB_API = 'https://api.github.com/repos/naishtech/cadet-agent/releases/latest';
+const USER_AGENT = 'cadet-agent-cli';
+
+// ── ZIP parser (zero-dependency, handles store + deflate) ───────────────────
+
+const SIG_EOCD  = 0x06054b50;
+const SIG_CD    = 0x02014b50;
+const SIG_LFH   = 0x04034b50;
+
+function read32(buf, off) { return buf.readUInt32LE(off); }
+function read16(buf, off) { return buf.readUInt16LE(off); }
+
+function findEocd(buf) {
+  // Search backwards from end for EOCD signature (comment is max 65535 bytes)
+  const maxStart = Math.max(0, buf.length - 65535 - 22);
+  for (let i = buf.length - 22; i >= maxStart; i--) {
+    if (read32(buf, i) === SIG_EOCD) return i;
+  }
+  throw new Error('Not a valid ZIP file: EOCD signature not found');
+}
+
+function* centralDirectoryEntries(buf, cdOffset, cdSize) {
+  let off = cdOffset;
+  const end = cdOffset + cdSize;
+  while (off < end) {
+    if (read32(buf, off) !== SIG_CD) break;
+    const method           = read16(buf, off + 10);
+    const compressedSize   = read32(buf, off + 20);
+    const uncompressedSize = read32(buf, off + 24);
+    const filenameLen      = read16(buf, off + 28);
+    const extraLen         = read16(buf, off + 30);
+    const commentLen       = read16(buf, off + 32);
+    const localHeaderOff   = read32(buf, off + 42);
+    const filename         = buf.toString('utf-8', off + 46, off + 46 + filenameLen);
+
+    // Skip directory entries (trailing / in filename, or uncompressedSize == 0 with no method)
+    if (!filename.endsWith('/')) {
+      yield { filename, method, compressedSize, uncompressedSize, localHeaderOff };
+    }
+
+    off += 46 + filenameLen + extraLen + commentLen;
+  }
+}
+
+function extractFile(buf, entry, targetDir) {
+  const { filename, method, compressedSize, localHeaderOff } = entry;
+
+  // Read local file header to get filename + extra lengths (they may differ from CD)
+  const lfhFilenameLen = read16(buf, localHeaderOff + 26);
+  const lfhExtraLen    = read16(buf, localHeaderOff + 28);
+
+  const dataStart = localHeaderOff + 30 + lfhFilenameLen + lfhExtraLen;
+  const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+
+  let data;
+  if (method === 0) {
+    // Stored — no compression
+    data = compressed;
+  } else if (method === 8) {
+    // Deflate
+    data = inflateRawSync(compressed);
+  } else {
+    throw new Error(`Unsupported compression method ${method} for ${filename}`);
+  }
+
+  const outPath = join(targetDir, filename);
+  mkdirSync(dirname(outPath), { recursive: true });
+  const ws = createWriteStream(outPath);
+  Readable.from(data).pipe(ws);
+
+  return outPath;
+}
+
+function extractZip(buf, targetDir) {
+  const eocdOff = findEocd(buf);
+  const cdSize  = read32(buf, eocdOff + 12);
+  const cdOff   = read32(buf, eocdOff + 16);
+
+  const paths = [];
+  for (const entry of centralDirectoryEntries(buf, cdOff, cdSize)) {
+    const outPath = extractFile(buf, entry, targetDir);
+    paths.push(outPath);
+  }
+  return paths;
+}
+
+// ── GitHub release download ─────────────────────────────────────────────────
+
+async function fetchLatestRelease() {
+  console.log('🔍 Fetching latest Cadet-Agent release...');
+
+  const res = await fetch(GITHUB_API, {
+    headers: {
+      'User-Agent': USER_AGENT,
+      'Accept': 'application/vnd.github+json',
+    },
+  });
+
+  if (!res.ok) {
+    if (res.status === 403 || res.status === 429) {
+      throw new Error(
+        `GitHub API rate-limited (${res.status}). ` +
+        'Set GITHUB_TOKEN env var for higher limits, or try again later.'
+      );
+    }
+    throw new Error(`GitHub API returned ${res.status}: ${res.statusText}`);
+  }
+
+  return res.json();
+}
+
+function findZipAsset(release) {
+  const asset = release.assets?.find(a => a.name === 'cadet-agent.zip');
+  if (!asset) {
+    throw new Error(
+      `Release ${release.tag_name} does not contain cadet-agent.zip.\n` +
+      `Available assets: ${(release.assets || []).map(a => a.name).join(', ') || 'none'}`
+    );
+  }
+  return asset;
+}
+
+async function downloadZip(url) {
+  console.log('⬇️  Downloading cadet-agent.zip...');
+
+  const res = await fetch(url, {
+    headers: {
+      'User-Agent': USER_AGENT,
+      'Accept': 'application/octet-stream',
+    },
+  });
+
+  if (!res.ok) {
+    throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+  }
+
+  const contentLength = res.headers.get('content-length');
+  const total = contentLength ? parseInt(contentLength, 10) : 0;
+
+  // Stream to buffer with progress
+  const chunks = [];
+  let downloaded = 0;
+  const reader = res.body.getReader();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    downloaded += value.length;
+    if (total > 0) {
+      const pct = Math.round((downloaded / total) * 100);
+      process.stdout.write(`\r   ${pct}% (${(downloaded / 1024).toFixed(0)} KB / ${(total / 1024).toFixed(0)} KB)`);
+    }
+  }
+  if (total > 0) process.stdout.write('\n');
+
+  return Buffer.concat(chunks);
+}
+
+// ── Public install entry ────────────────────────────────────────────────────
+
+export async function install(targetDir) {
+  console.log(`📦 Cadet-Agent — installing to ${targetDir}\n`);
+
+  // 1. Fetch release metadata
+  const release = await fetchLatestRelease();
+  console.log(`   Latest: ${release.tag_name} (published ${release.published_at})\n`);
+
+  // 2. Find zip asset
+  const asset = findZipAsset(release);
+
+  // 3. Download
+  const zipBuf = await downloadZip(asset.browser_download_url);
+  console.log(`   Downloaded ${(zipBuf.length / 1024).toFixed(0)} KB\n`);
+
+  // 4. Extract
+  console.log('📂 Extracting...');
+  const extracted = extractZip(zipBuf, targetDir);
+
+  // 5. Report
+  console.log(`\n✅ Cadet-Agent ${release.tag_name} installed! Extracted ${extracted.length} files.\n`);
+
+  // Print per-IDE next steps
+  console.log('── Next steps ──');
+  console.log('  GitHub Copilot:');
+  console.log('    Rename .github\\cadet-copilot-instructions.md → .github\\copilot-instructions.md');
+  console.log('    Then start a chat: /cadet');
+  console.log('  Cursor:');
+  console.log('    Already active — .cursor\\rules\\cadet-agent.md loads automatically');
+  console.log('  Continue:');
+  console.log('    Already active — .continue\\rules\\cadet-agent.md loads automatically');
+  console.log('  Claude Code:');
+  console.log('    Already active — .claude\\skills\\cadet-agent.md loads as a project skill');
+  console.log('');
+}