orca-agent-cleanup 0.0.0-stage → 1.5.0

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+![Orca Agent Cleanup](https://raw.githubusercontent.com/wilgon456/orca-agent-cleanup/main/docs/readme-banner.svg)
+
+# Orca Agent Cleanup
+
+Inspect leftover Orca integrations, quarantine verified residue and restore it when needed.
+
+**English** · [한국어](README.ko.md)
+
+![project: utility](https://img.shields.io/badge/project-utility-22d3ee?style=flat-square) ![stack: Node.js 18+](https://img.shields.io/badge/stack-Node.js%2018%2B-22d3ee?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
+
+[Quick start](#quick-start) · [Coverage](#cleanup-coverage) · [Restore](#restore)
+
+</div>
+
+---
+
+> [!IMPORTANT]
+> This is an independent community tool, unaffiliated with Orca or Stably. Uninstall the Orca app normally and close related coding-agent sessions before applying cleanup.
+
+## Why use it
+
+Removing Orca can leave shared skills, agent hooks, launchers, cached models and configuration behind. Agents may keep trying to call a missing Orca CLI or computer-use integration. This tool identifies residue using the upstream Orca manifest, ownership markers and signatures, then moves verified items into a recoverable backup.
+
+It does **not** uninstall the Orca application itself.
+
+## Quick start
+
+Requires **Node.js 18 or newer**. The commands work in Windows PowerShell, macOS Terminal and Linux shells. Run it with `npx`; nothing needs to be installed.
+
+```bash
+npx orca-agent-cleanup scan
+```
+
+You can also clone the repository and replace `npx orca-agent-cleanup` with `node scripts/orca-agent-cleanup.mjs` in the commands below.
+
+```bash
+git clone https://github.com/wilgon456/orca-agent-cleanup.git
+cd orca-agent-cleanup
+```
+
+**Inspect** without changing files:
+
+```bash
+npx orca-agent-cleanup scan
+```
+
+**Preview** cleanup including application data, voice data and leftover Orca processes. If Orca is still installed or running you will see a ⛔ warning; uninstall the app first.
+
+```bash
+npx orca-agent-cleanup clean --dry-run --include-app-data --include-voice-data --stop-processes
+```
+
+**Apply** the reviewed cleanup:
+
+```bash
+npx orca-agent-cleanup clean --include-app-data --include-voice-data --stop-processes
+```
+
+The command reports the backup location. Replace the placeholder below with that actual path:
+
+```bash
+npx orca-agent-cleanup verify --manifest /path/to/backup/manifest.json
+```
+
+Restart your coding agents and terminals afterward so their cached skill lists and environment variables are refreshed.
+
+## Cleanup coverage
+
+| Target | Included by default? |
+| --- | --- |
+| Eight official Orca skills and signed copies in Codex plugin caches | Yes, after ownership verification |
+| Orca-managed agent hooks and marked extensions (24 agent integrations, see below) | Yes |
+| Verified user CLI launchers and Orca PATH entries | Yes |
+| Orca background processes left running after the app was removed | `--stop-processes` |
+| Managed hooks and Orca-encrypted credentials under `~/.orca` | Yes |
+| App data and its default voice models | `--include-app-data` |
+| Separate voice caches and custom model locations | `--include-voice-data` |
+| Running WSL distributions | `--include-wsl` |
+| Accessible remote homes | `--include-remote` |
+| All user state under `~/.orca` | `--include-user-state` |
+| Project `.orca` state and adjacent worktree trash | `--include-project-state` |
+
+Hook cleanup follows every agent integration in Orca's `src/main/*/hook-service.ts`: Claude, OpenClaude, Codex, Gemini, Antigravity, Cursor, Command Code, Droid, Copilot, Grok, Devin, Kimi, Amp, Hermes, Qoder (including Qoder CN), Qwen Code, CodeBuddy, ZCode, Kiro (each agent file in `~/.kiro/agents`), Muse, jcode, DeepSeek Harness (`~/.dsh/cordis.patch.yml`), OpenCode (status plugins and `tui.json` registrations) and MiMo Code (inside app data). Windows hook commands wrapped in PowerShell or `-EncodedCommand` are decoded before matching. Only Orca entries are removed; the rest of each file is kept.
+
+The credential files are `openai-speech-token.enc`, `bitbucket-credential.*`, `linear-token.enc`, `linear-workspaces.json`, `jira-tokens`, `jira-sites.json`, `zcode-plan-api-key.enc`, `opencode-go-api-key.enc` and `minimax-*.enc`. Orca encrypts them with its own app key, so they are useless once the app is gone. Other files under `~/.orca`, such as worktrees and `keybindings.json`, stay unless you pass `--include-user-state`.
+
+The official skill names are `computer-use`, `orca-cli`, `orchestration`, `orca-per-workspace-env`, `orca-emulator`, `orca-emulator-android`, `orca-linear` and `linear-tickets`. A matching name alone is insufficient: unrelated providers' skills, including OpenAI's computer-use and Paseo skills, are preserved.
+
+## Platforms
+
+| Platform | Relevant locations |
+| --- | --- |
+| Windows 10 / 11 | User skill folders, `%APPDATA%`, `%LOCALAPPDATA%`, verified `ProgramData` / `Public` voice caches and user PATH |
+| macOS | User skill folders, Stably app data under `~/Library`, verified `/usr/local/bin/orca` and `~/.local/bin/orca` launchers |
+| Linux | Orca config/cache directories, AppImage cache, official `orca-ide` launcher and marked Orca dispatcher |
+
+Linux's `/usr/bin/orca` is the GNOME screen reader and is never targeted. System-managed or headless-server installations are outside automatic cleanup.
+
+## Safeguards
+
+- `scan` is read-only; `clean --dry-run` previews the proposed operations.
+- File names are checked together with provenance and Orca-specific markers.
+- Targets are quarantined rather than permanently deleted.
+- Configuration changes remove identified Orca entries while preserving unrelated settings and saving the original.
+- Manifest v2 is written before cleanup and updated around each operation so interrupted runs can be recovered.
+- File and directory SHA-256 hashes support backup verification.
+- Default backup folders include a UUID; unsafe or nonempty custom destinations are rejected.
+- Items with insufficient provenance are reported as `unverified` and left alone.
+
+Default backups live under `~/OrcaAgentCleanupBackups/<timestamp-UUID>/`. They contain `manifest.json`, original configurations and categorized quarantined files.
+
+## Restore
+
+Close related applications, verify the backup, then preview restoration:
+
+```bash
+npx orca-agent-cleanup verify --manifest /path/to/backup/manifest.json
+npx orca-agent-cleanup restore --dry-run --manifest /path/to/backup/manifest.json
+npx orca-agent-cleanup restore --manifest /path/to/backup/manifest.json
+```
+
+Manifest v1 backups remain supported, but they lack the content hashes recorded by v2. An `in-progress` v2 journal can recover operations that reached the backup even if the original cleanup was interrupted.
+
+If a restore destination has changed, its current contents are preserved in `restore-conflicts/` before the original is restored. Restoration writes a separate report and skips identical items already restored. Keep the backup until you have checked that your agents work correctly.
+
+## Options
+
+| Option | Purpose |
+| --- | --- |
+| `scan`, `clean`, `verify`, `restore` | Inspect, quarantine, verify integrity or recover |
+| `--dry-run` | Preview cleanup or restoration |
+| `--stop-processes` | Stop Orca background processes left running without the app; not restorable |
+| `--force` | Clean even while Orca is installed or running; not recommended because the app reinstalls its hooks |
+| `--project <path>` | Add a project's skill folders; repeatable |
+| `--include-app-data`, `--include-voice-data` | Include explicitly selected application / voice residue |
+| `--voice-model-path <path>` | Add a custom voice model path; repeatable |
+| `--include-wsl`, `--wsl-home <path>` | Inspect running WSL distributions or specified WSL homes |
+| `--include-remote`, `--remote-home <path>` | Include an accessible remote home; no automatic SSH login |
+| `--include-user-state` | Quarantine all `~/.orca` state, including sessions and credentials |
+| `--include-project-state` | Include the selected project's `.orca` state and worktree trash |
+| `--backup-root <path>` | Choose a backup destination |
+| `--manifest <path>` | Select a backup for verification or restoration |
+| `--json` | Return structured output |
+
+Use `npx orca-agent-cleanup --help` for the complete interface. In PowerShell, use single-line commands or PowerShell backticks rather than Bash line continuations.
+
+## Boundaries
+
+Automatic cleanup does not remove the app, change macOS privacy permissions, uninstall Windows app entries, delete package-managed Linux installations, start stopped WSL distributions or log into SSH hosts. It preserves unverified skills, user source/workspaces, historical chats and credentials belonging to other software.
+
+The app can be uninstalled through Windows Settings, the macOS Applications folder or the Linux installation method you originally used. Complete that step before cleaning its integrations.
+
+## Version 1.5.0
+
+This version runs with `npx orca-agent-cleanup`. `clean` now stops when the Orca app is still installed or running, because Orca reinstalls its hooks and plugins on launch and quarantining its credentials would break a working app; `--force` overrides this. Orca terminal daemons left running after uninstalling are reported by executable location and stopped with `--stop-processes`. Files Orca creates outright, such as Copilot `hooks/orca.json` and Grok `hooks/orca-status.json`, are quarantined whole instead of being left as empty shells when nothing but Orca entries remain.
+
+## Version 1.4.0
+
+This version is checked against Orca v1.4.224 and the 2026-10-14 `main` branch. It adds hook cleanup for Qoder, Qwen Code, CodeBuddy, ZCode, Kiro, Muse, jcode, DeepSeek Harness and OpenCode, catches PowerShell-wrapped and base64-encoded Windows hook commands, quarantines Orca's newer encrypted credentials, scans three new skill folders and makes the upstream monitor flag new or removed agent integrations.
+
+## Version 1.3.0
+
+Version 1.3.0 added Linux AppImage and signed plugin-cache coverage, recovery journals, backup hashes, UUID destinations, upstream contract monitoring, SHA-pinned Actions and Node.js 24 / CodeQL checks.
+
+## Development
+
+Tests use temporary fixture homes rather than real user settings:
+
+```bash
+node --test tests/orca-agent-cleanup.test.mjs
+```
+
+The legacy Windows interface remains available:
+
+```powershell
+.\scripts\Get-OrcaAgentResidue.ps1
+.\scripts\Remove-OrcaAgentIntegrations.ps1 -Apply -IncludeAppData -WhatIf
+.\tests\Invoke-SmokeTest.ps1
+```
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting. For bug reports, include the OS, whether Orca was uninstalled, a redacted scan result and the expected versus observed behavior.
+
+## License
+
+[MIT](LICENSE).

package/package.json

@@ -1,6 +1,42 @@
-{
-  "name": "orca-agent-cleanup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "orca-agent-cleanup",
+  "version": "1.5.0",
+  "description": "Find and safely quarantine leftover Orca (stablyai/orca) skills, agent hooks, CLI launchers, credentials and app data after uninstalling Orca, with verified restore.",
+  "keywords": [
+    "orca",
+    "stablyai",
+    "uninstall",
+    "cleanup",
+    "claude-code",
+    "codex",
+    "agent-hooks",
+    "skills"
+  ],
+  "license": "MIT",
+  "author": "wilgon456",
+  "homepage": "https://github.com/wilgon456/orca-agent-cleanup#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilgon456/orca-agent-cleanup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wilgon456/orca-agent-cleanup/issues"
+  },
+  "type": "module",
+  "bin": {
+    "orca-agent-cleanup": "scripts/orca-agent-cleanup.mjs"
+  },
+  "files": [
+    "scripts/orca-agent-cleanup.mjs",
+    "scripts/orca-cleanup-core.mjs",
+    "README.md",
+    "README.ko.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test tests/orca-agent-cleanup.test.mjs"
+  }
+}

package/scripts/orca-agent-cleanup.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import process from 'node:process';
+import {
+  buildContext,
+  cleanOrcaResidue,
+  OFFICIAL_ORCA_SKILLS,
+  restoreOrcaBackup,
+  scanOrcaResidue,
+  verifyOrcaBackup,
+} from './orca-cleanup-core.mjs';
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+const HELP = `
+Orca Agent Cleanup v${VERSION} : Windows·macOS·Linux 공통 정리 도구
+
+사용법:
+  npx orca-agent-cleanup scan [옵션]
+  npx orca-agent-cleanup clean [옵션]
+  npx orca-agent-cleanup restore --manifest <manifest.json> [옵션]
+  npx orca-agent-cleanup verify --manifest <manifest.json> [옵션]
+
+저장소에서 직접 실행할 때는 npx orca-agent-cleanup 대신 node scripts/orca-agent-cleanup.mjs를 씁니다.
+
+명령:
+  scan                         잔재를 검사합니다(기본 명령, 변경 없음).
+  clean                        확인된 잔재를 백업 폴더로 격리합니다.
+  restore                      manifest에 기록된 파일과 설정을 복원합니다.
+  verify                       manifest와 백업 내용의 무결성을 검사합니다.
+
+옵션:
+  --dry-run                    clean의 예정 작업만 표시합니다.
+  --stop-processes             앱 없이 남아 도는 Orca 백그라운드 프로세스를 끕니다.
+  --force                      Orca 앱이 설치·실행 중이어도 정리합니다(권장하지 않음).
+  --include-app-data           Orca 앱 데이터·캐시를 포함합니다.
+  --include-voice-data         별도 음성 모델 캐시를 포함합니다.
+  --include-user-state         ~/.orca 전체(자격증명·세션 포함)를 포함합니다.
+  --include-wsl                실행 중인 WSL 배포판의 Orca 잔재를 검사·정리합니다.
+  --wsl-home <경로>            WSL 홈 경로를 직접 추가합니다(반복 가능).
+  --include-remote             SSH 릴레이·원격 세션 잔재를 포함합니다.
+  --remote-home <경로>         접근 가능한 원격 홈 경로를 추가합니다(반복 가능).
+  --include-project-state      --project의 .orca·worktree 휴지통을 포함합니다.
+  --project <경로>             프로젝트 스킬 위치를 추가합니다(반복 가능).
+  --voice-model-path <경로>    사용자 지정 음성 모델 경로를 포함합니다(반복 가능).
+  --backup-root <경로>         격리·백업 폴더를 지정합니다.
+  --manifest <경로>            restore·verify에 사용할 manifest.json을 지정합니다.
+  --json                       결과를 JSON으로 출력합니다.
+  -v, --version                버전을 표시합니다.
+  -h, --help                   도움말을 표시합니다.
+
+예시:
+  npx orca-agent-cleanup scan
+  npx orca-agent-cleanup clean --dry-run --include-app-data --include-voice-data --stop-processes
+  npx orca-agent-cleanup clean --include-app-data --include-voice-data --stop-processes
+  npx orca-agent-cleanup restore --dry-run --manifest /path/to/manifest.json
+`;
+
+function parseArgs(argv) {
+  const result = {
+    command: 'scan', projects: [], customVoicePaths: [], wslHomes: [], remoteHomes: [], json: false,
+    dryRun: false, force: false, stopProcesses: false, includeAppData: false, includeVoiceData: false,
+    includeUserState: false, includeWsl: false, includeRemote: false, includeProjectState: false,
+  };
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith('-')) result.command = args.shift();
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--dry-run') result.dryRun = true;
+    else if (arg === '--force') result.force = true;
+    else if (arg === '--stop-processes') result.stopProcesses = true;
+    else if (arg === '--include-app-data') result.includeAppData = true;
+    else if (arg === '--include-voice-data') result.includeVoiceData = true;
+    else if (arg === '--include-user-state') result.includeUserState = true;
+    else if (arg === '--include-wsl') result.includeWsl = true;
+    else if (arg === '--include-remote') result.includeRemote = true;
+    else if (arg === '--include-project-state') result.includeProjectState = true;
+    else if (arg === '--json') result.json = true;
+    else if (arg === '-v' || arg === '--version') result.version = true;
+    else if (arg === '-h' || arg === '--help') result.help = true;
+    else if (arg === '--project') result.projects.push(requireValue(arg, args));
+    else if (arg === '--wsl-home') result.wslHomes.push(requireValue(arg, args));
+    else if (arg === '--remote-home') result.remoteHomes.push(requireValue(arg, args));
+    else if (arg === '--voice-model-path') result.customVoicePaths.push(requireValue(arg, args));
+    else if (arg === '--backup-root') result.backupRoot = requireValue(arg, args);
+    else if (arg === '--manifest') result.manifestPath = requireValue(arg, args);
+    else throw new Error(`알 수 없는 옵션입니다: ${arg}`);
+  }
+  if (!['scan', 'clean', 'restore', 'verify'].includes(result.command)) throw new Error(`알 수 없는 명령입니다: ${result.command}`);
+  if (['restore', 'verify'].includes(result.command) && !result.manifestPath && !result.help && !result.version) {
+    throw new Error(`${result.command}에는 --manifest <경로>가 필요합니다.`);
+  }
+  return result;
+}
+
+function requireValue(option, args) {
+  const value = args.shift();
+  if (!value || value.startsWith('--')) throw new Error(`${option} 뒤에 경로가 필요합니다.`);
+  return value;
+}
+
+function icon(kind) {
+  return ({ skill: '🧩', 'skill-lock': '🔒', hook: '🪝', 'shared-state': '🔗',
+    'skill-transaction': '🧹', extension: '🧱', 'app-data': '🗂️', 'voice-data': '🎙️',
+    'user-state': '🔐', 'wsl-state': '🐧', 'remote-state': '🌐', cli: '⌨️',
+    'project-state': '📁', 'app-installed': '⛔', 'app-running': '⛔', process: '⚙️',
+    'path-entry': '🛣️', unverified: '🛡️' })[kind] || '•';
+}
+
+function printScan(findings) {
+  console.log('\nOrca Agent Cleanup 검사 결과\n');
+  if (!findings.length) {
+    console.log('✅ 확인된 Orca 잔재가 없습니다.');
+    return;
+  }
+  for (const item of findings) {
+    const option = item.requires ? ` [정리 시 --${item.requires.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)} 필요]` : '';
+    console.log(`${icon(item.kind)} ${item.path}`);
+    console.log(`   ${item.reason}${option}`);
+  }
+  console.log(`\n총 ${findings.length}개가 확인되었습니다. 검사만 수행했으며 변경 사항은 없습니다.`);
+  if (findings.some((item) => ['app-installed', 'app-running'].includes(item.kind))) {
+    console.log('\n⛔ Orca 앱이 아직 설치돼 있거나 실행 중입니다. 앱이 켜질 때 훅을 다시 설치하므로 먼저 앱을 제거하세요. 그 전까지 clean은 멈춥니다.');
+  }
+}
+
+function printClean(result) {
+  console.log(`\nOrca Agent Cleanup ${result.dryRun ? '미리보기' : '정리 결과'}\n`);
+  if (result.blocked && !result.dryRun) {
+    console.log(`⛔ ${result.errors[0].message}`);
+    return;
+  }
+  if (result.blocked) {
+    console.log('⛔ Orca 앱이 아직 설치돼 있거나 실행 중입니다. 실제 clean은 앱을 제거하기 전까지 멈춥니다.\n');
+  }
+  if (!result.actions.length) {
+    console.log('✅ 정리할 항목이 없습니다.');
+    return;
+  }
+  const labels = {
+    quarantined: '✅ 격리', edited: '✅ 수정', 'would-quarantine': '🔎 격리 예정',
+    'would-edit': '🔎 수정 예정', skipped: '⏭️ 옵션 제외', covered: '↳ 상위 상태에 포함',
+    unchanged: '➖ 변경 없음', error: '❌ 오류',
+    'pending-quarantine': '⚠️ 격리 상태 확인 필요', 'pending-edit': '⚠️ 수정 상태 확인 필요',
+    stopped: '✅ 프로세스 끔', 'would-stop': '🔎 프로세스 끌 예정',
+  };
+  for (const item of result.actions) console.log(`${labels[item.action] || item.action}  ${item.path}`);
+  if (!result.dryRun && result.actions.some((item) => ['quarantined', 'edited'].includes(item.action))) {
+    console.log(`\n복구용 백업: ${result.backupRoot}`);
+  }
+  if (result.errors.length) console.log(`\n⚠️ ${result.errors.length}개 항목은 자동 처리하지 못했습니다. 위 오류를 확인하세요.`);
+}
+
+function printRestore(result) {
+  console.log(`\nOrca Agent Cleanup ${result.dryRun ? '복원 미리보기' : '복원 결과'}\n`);
+  if (result.cleanupStatus === 'in-progress') {
+    console.log('⚠️ 중단된 정리 journal을 복구합니다. 해시 기록 전 중단된 항목은 백업 존재 여부로 판정합니다.\n');
+  }
+  if (!result.actions.length) {
+    console.log('✅ manifest에 복원할 완료 작업이 없습니다.');
+    return;
+  }
+  const labels = {
+    restored: '✅ 복원', 'would-restore': '🔎 복원 예정',
+    'already-restored': '➖ 이미 복원됨', error: '❌ 오류',
+  };
+  for (const item of result.actions) {
+    console.log(`${labels[item.action] || item.action}  ${item.path}`);
+    if (item.conflictBackup) console.log(`   현재 항목 보존: ${item.conflictBackup}`);
+  }
+  if (result.reportPath) console.log(`\n복원 보고서: ${result.reportPath}`);
+  if (result.errors.length) console.log(`\n⚠️ ${result.errors.length}개 항목은 복원하지 못했습니다.`);
+}
+
+function printVerify(result) {
+  console.log('\nOrca Agent Cleanup 백업 검증 결과\n');
+  const labels = {
+    verified: '✅ 검증됨', 'not-recorded': 'ℹ️ v1 해시 없음',
+    'not-applied': '➖ 미적용', 'recoverable-unverified': '⚠️ 중단 작업', error: '❌ 오류',
+  };
+  for (const item of result.actions) console.log(`${labels[item.status] || item.status}  ${item.backup || item.path}`);
+  console.log(result.valid ? '\n✅ manifest와 백업을 사용할 수 있습니다.' : `\n❌ ${result.errors.length}개 오류가 있습니다.`);
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.version) {
+    console.log(VERSION);
+    process.exit(0);
+  } else if (options.help) {
+    console.log(HELP.trim());
+    process.exit(0);
+  }
+  if (options.command === 'verify') {
+    const result = verifyOrcaBackup(options.manifestPath, options);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else printVerify(result);
+    if (!result.valid) process.exitCode = 2;
+  } else if (options.command === 'restore') {
+    const result = restoreOrcaBackup(options.manifestPath, options);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else printRestore(result);
+    if (result.errors.length) process.exitCode = 2;
+  } else if (options.command === 'scan') {
+    const context = buildContext(options);
+    const findings = scanOrcaResidue(context);
+    if (options.json) console.log(JSON.stringify({ platform: context.platform, officialSkills: OFFICIAL_ORCA_SKILLS, findings }, null, 2));
+    else printScan(findings);
+  } else {
+    const context = buildContext(options);
+    const result = cleanOrcaResidue(context, options);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else printClean(result);
+    if (result.errors.length) process.exitCode = 2;
+  }
+} catch (error) {
+  console.error(`오류: ${error.message}`);
+  console.error('도움말: npx orca-agent-cleanup --help');
+  process.exitCode = 1;
+}