cadet-agent 0.4.0 → 0.5.0

package/README.md

@@ -11,6 +11,27 @@ Cadet-Agent is a cross-IDE agent framework for game-development workflows, with
 - `.continue/` contains Continue-specific authored files.
 - `.claude/` contains Claude Code-specific authored files.
 - `package-agent.ps1` builds the distributable `cadet-agent.zip` package.
+- `publish-npm.ps1` publishes the CLI to npm using a token from `~/.npm_token`.
+
+## Quick Install
+
+```bash
+npx cadet-agent@latest init
+```
+
+This downloads the latest framework release and extracts it into your current directory. For a specific target directory:
+
+```bash
+npx cadet-agent@latest init --target ./my-unity-project
+```
+
+## Manual Install
+
+Download `cadet-agent.zip` from [GitHub Releases](https://github.com/naishtech/cadet-agent/releases) and extract it into your Unity project root:
+
+```powershell
+Expand-Archive .\cadet-agent.zip -DestinationPath . -Force
+```
 
 ## Getting Started
 - For repository setup and package contents, see [.cadet/agent/README.md](.cadet/agent/README.md).
@@ -23,7 +44,7 @@ Cadet-Agent is a cross-IDE agent framework for game-development workflows, with
 ## 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.
+Run `npx cadet-agent@latest init` in your Unity project root, then 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.
@@ -59,7 +80,6 @@ If a specific game repository needs local conventions, add a policy file under `
 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadet-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { install } from './install.mjs';
+import { install, sync } from './install.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -25,9 +25,12 @@ function showHelp() {
   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
+    npx cadet-agent@latest sync     Update framework, preserving local policies/plans
+    npx cadet-agent@latest sync --target <dir>   Sync a specific directory
 
   Options:
     --target, -t  Target directory (default: current working directory)
+    --source       Release API URL override (for forked deployments)
     --help, -h    Show this help
     --version, -v Show version number
 `);
@@ -38,17 +41,25 @@ export async function run(argv) {
 
   // Parse --target <dir> or -t <dir>
   let targetDir = process.cwd();
+  let sourceUrl = null;
   const targetIdx = argv.indexOf('--target');
   const tIdx = argv.indexOf('-t');
+  const sourceIdx = argv.indexOf('--source');
   if (targetIdx !== -1 && argv[targetIdx + 1]) {
     targetDir = argv[targetIdx + 1];
   } else if (tIdx !== -1 && argv[tIdx + 1]) {
     targetDir = argv[tIdx + 1];
   }
+  if (sourceIdx !== -1 && argv[sourceIdx + 1]) {
+    sourceUrl = argv[sourceIdx + 1];
+  }
 
   switch (command) {
     case 'init':
-      await install(targetDir);
+      await install(targetDir, { sourceUrl });
+      break;
+    case 'sync':
+      await sync(targetDir, { sourceUrl });
       break;
     case '--version':
     case '-v':

package/src/install.mjs

@@ -1,4 +1,4 @@
-import { createWriteStream, mkdirSync, existsSync } from 'node:fs';
+import { createWriteStream, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { createGunzip } from 'node:zlib';
@@ -8,9 +8,13 @@ import { Readable } from 'node:stream';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
-const GITHUB_API = 'https://api.github.com/repos/naishtech/cadet-agent/releases/latest';
+const DEFAULT_API = 'https://api.github.com/repos/naishtech/cadet-agent/releases/latest';
 const USER_AGENT = 'cadet-agent-cli';
 
+function resolveApiUrl(override) {
+  return override || process.env.CADET_AGENT_RELEASE_URL || DEFAULT_API;
+}
+
 // ── ZIP parser (zero-dependency, handles store + deflate) ───────────────────
 
 const SIG_EOCD  = 0x06054b50;
@@ -70,7 +74,12 @@ function extractFile(buf, entry, targetDir) {
     // Deflate
     data = inflateRawSync(compressed);
   } else {
-    throw new Error(`Unsupported compression method ${method} for ${filename}`);
+    throw new Error(
+      `Unsupported compression method ${method} for ${filename}.\n` +
+      `This zip uses a compression format this CLI doesn't support.\n` +
+      `Try downloading cadet-agent.zip manually from:\n` +
+      `  https://github.com/naishtech/cadet-agent/releases/latest`
+    );
   }
 
   const outPath = join(targetDir, filename);
@@ -86,6 +95,15 @@ function extractZip(buf, targetDir) {
   const cdSize  = read32(buf, eocdOff + 12);
   const cdOff   = read32(buf, eocdOff + 16);
 
+  // ZIP64 detection — 0xFFFFFFFF in 32-bit fields means real values are in ZIP64 extra records
+  if (cdOff === 0xFFFFFFFF || cdSize === 0xFFFFFFFF) {
+    throw new Error(
+      'This zip uses ZIP64 format, which is not supported.\n' +
+      'Try downloading cadet-agent.zip manually from:\n' +
+      '  https://github.com/naishtech/cadet-agent/releases/latest'
+    );
+  }
+
   const paths = [];
   for (const entry of centralDirectoryEntries(buf, cdOff, cdSize)) {
     const outPath = extractFile(buf, entry, targetDir);
@@ -96,10 +114,11 @@ function extractZip(buf, targetDir) {
 
 // ── GitHub release download ─────────────────────────────────────────────────
 
-async function fetchLatestRelease() {
+async function fetchLatestRelease(apiUrl) {
+  const url = resolveApiUrl(apiUrl);
   console.log('🔍 Fetching latest Cadet-Agent release...');
 
-  const res = await fetch(GITHUB_API, {
+  const res = await fetch(url, {
     headers: {
       'User-Agent': USER_AGENT,
       'Accept': 'application/vnd.github+json',
@@ -169,11 +188,11 @@ async function downloadZip(url) {
 
 // ── Public install entry ────────────────────────────────────────────────────
 
-export async function install(targetDir) {
+export async function install(targetDir, opts = {}) {
   console.log(`📦 Cadet-Agent — installing to ${targetDir}\n`);
 
   // 1. Fetch release metadata
-  const release = await fetchLatestRelease();
+  const release = await fetchLatestRelease(opts.sourceUrl);
   console.log(`   Latest: ${release.tag_name} (published ${release.published_at})\n`);
 
   // 2. Find zip asset
@@ -193,8 +212,7 @@ export async function install(targetDir) {
   // 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('    Start a chat: /cadet');
   console.log('  Cursor:');
   console.log('    Already active — .cursor\\rules\\cadet-agent.md loads automatically');
   console.log('  Continue:');
@@ -203,3 +221,117 @@ export async function install(targetDir) {
   console.log('    Already active — .claude\\skills\\cadet-agent.md loads as a project skill');
   console.log('');
 }
+
+// ── Manifest-aware extraction ───────────────────────────────────────────────
+
+function matchesPreservedPath(filename, preservedPaths) {
+  // Normalize: strip leading dot (zip paths like ".cadet/agent/policies/...")
+  const normalized = filename.replace(/^\.?\/?/, '');
+  for (const preserved of preservedPaths) {
+    const p = preserved.replace(/^\.?\/?/, '');
+    if (normalized === p || normalized.startsWith(p + '/') || normalized.startsWith(p + '\\')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function extractZipWithManifest(buf, targetDir, { preserved, managed }) {
+  const eocdOff = findEocd(buf);
+  const cdSize  = read32(buf, eocdOff + 12);
+  const cdOff   = read32(buf, eocdOff + 16);
+
+  if (cdOff === 0xFFFFFFFF || cdSize === 0xFFFFFFFF) {
+    throw new Error(
+      'This zip uses ZIP64 format, which is not supported.\n' +
+      'Try downloading cadet-agent.zip manually from:\n' +
+      '  https://github.com/naishtech/cadet-agent/releases/latest'
+    );
+  }
+
+  const updated = [];
+  const preserved_list = [];
+  const added = [];
+
+  for (const entry of centralDirectoryEntries(buf, cdOff, cdSize)) {
+    if (matchesPreservedPath(entry.filename, preserved)) {
+      preserved_list.push(entry.filename);
+      continue;
+    }
+    const outPath = extractFile(buf, entry, targetDir);
+    // Check if this file already existed (updated vs added)
+    // We can't easily tell without checking before extraction, so approximate:
+    // If it's under a managed path, call it updated; otherwise added
+    const isManaged = managed.some(m => {
+      const mn = m.replace(/^\.?\/?/, '');
+      const fn = entry.filename.replace(/^\.?\/?/, '');
+      return fn === mn || fn.startsWith(mn + '/') || fn.startsWith(mn + '\\');
+    });
+    if (isManaged) {
+      updated.push(outPath);
+    } else {
+      added.push(outPath);
+    }
+  }
+
+  return { updated, preserved: preserved_list, added };
+}
+
+// ── Public sync entry ───────────────────────────────────────────────────────
+
+export async function sync(targetDir, opts = {}) {
+  console.log(`🔄 Cadet-Agent — syncing ${targetDir}\n`);
+
+  // 1. Read existing manifest
+  const manifestPath = join(targetDir, '.cadet', 'agent', 'core', 'FrameworkManifest.json');
+  let existingManifest = null;
+  let oldVersion = 'none';
+  try {
+    existingManifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    oldVersion = existingManifest.frameworkVersion || 'unknown';
+    console.log(`   Existing install: v${oldVersion}`);
+  } catch {
+    console.log('   No existing install found — performing full install.\n');
+    return install(targetDir, opts);
+  }
+
+  // 2. Fetch release metadata
+  const release = await fetchLatestRelease(opts.sourceUrl);
+  const newVersion = release.tag_name;
+  console.log(`   Latest: ${newVersion} (published ${release.published_at})\n`);
+
+  if (oldVersion === newVersion) {
+    console.log(`✅ Already up to date (v${oldVersion}). Nothing to sync.\n`);
+    return;
+  }
+
+  // 3. Download
+  const asset = findZipAsset(release);
+  const zipBuf = await downloadZip(asset.browser_download_url);
+  console.log(`   Downloaded ${(zipBuf.length / 1024).toFixed(0)} KB\n`);
+
+  // 4. Extract with manifest awareness
+  console.log('📂 Extracting (preserving local policies and plans)...');
+  const result = extractZipWithManifest(zipBuf, targetDir, {
+    preserved: existingManifest.preservedPaths || [],
+    managed: existingManifest.managedPaths || [],
+  });
+
+  // 5. Report
+  console.log('');
+  console.log(`✅ Cadet-Agent synced: v${oldVersion} → ${newVersion}`);
+  console.log(`   Updated:  ${result.updated.length} files`);
+  if (result.preserved.length > 0) {
+    console.log(`   Preserved: ${result.preserved.length} files (local policies/plans)`);
+  }
+  if (result.added.length > 0) {
+    console.log(`   New:      ${result.added.length} files`);
+  }
+  console.log('');
+
+  // Print per-IDE next steps
+  console.log('── Next steps ──');
+  console.log('  Framework files updated. Start a fresh chat for changes to take effect:');
+  console.log('    /cadet');
+  console.log('');
+}