@vigil-guard/vge-cc-guard 0.9.0-beta.1

package/LICENSE.md

@@ -0,0 +1,37 @@
+# Proprietary License
+
+Copyright (c) 2025 Vigil Guard. All Rights Reserved.
+
+## Terms and Conditions
+
+This software and associated documentation files (the "Software") are proprietary and confidential.
+
+### Restrictions
+
+1. **No Redistribution**: You may not copy, modify, merge, publish, distribute, sublicense, or sell copies of the Software.
+
+2. **No Reverse Engineering**: You may not reverse engineer, decompile, or disassemble the Software.
+
+3. **No Transfer**: You may not transfer, assign, or sublicense your rights under this license to any third party.
+
+4. **Confidentiality**: You must maintain the confidentiality of the Software and not disclose it to any third party without prior written consent.
+
+### Permitted Uses
+
+Use of this Software is permitted only:
+
+- Under a valid commercial license agreement
+- For authorized internal development and testing
+- By employees or contractors under NDA
+
+### Warranty Disclaimer
+
+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.
+
+### Limitation of Liability
+
+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.
+
+### Contact
+
+For licensing inquiries, please contact: contact@vigilguard.ai

package/README.md

@@ -0,0 +1,441 @@
+# vge-cc-guard
+
+`vge-cc-guard` is a local security sidecar for Claude Code. It installs Claude
+Code hooks, gates tool calls before execution, sends configured prompt and tool
+content to Vigil Guard Enterprise (VGE), manages user decisions for blocked
+content, and writes a private local audit trail.
+
+Current package version: `0.9.0-beta.1`.
+
+## Current State
+
+- Phase 1 is complete; Phase 2 PostTool enforcement is active.
+- Runtime is TypeScript on Node.js. The npm package declares
+  `node >=20.10.0`.
+- VGE is the only content detector. The sidecar is the hook broker, local
+  policy engine, state machine, quarantine layer, and audit writer.
+- `PostToolUse` supports explicit VGE block HITL/quarantine, research-safe
+  `SOFT_TAINT` framing for `WebSearch` and `WebFetch`, and fail-open overload
+  backpressure for research-tool scans.
+
+## What It Protects
+
+Claude Code can read files, run commands, fetch URLs, edit code, and spawn
+subagents. `vge-cc-guard` wraps those paths with:
+
+- PreTool gates from local tool policy.
+- Hard credential path protection for `Read`, `Edit`, `Write`, and prompt file
+  attachments.
+- Local deterministic URL deny-list checks for `Bash` and `WebFetch` targets.
+- VGE analysis for prompt text, prompt file attachments, and configured tool
+  outputs.
+- Session-scoped exact-resource allow/block decisions.
+- Owner-aware decisions for parent sessions and subagents.
+- Local audit JSONL and authenticated local decision metrics.
+
+The sidecar does not run local prompt-injection heuristics. URL target checks
+are the local exception: they are deterministic target-control rules, not
+content detection.
+
+## Runtime Model
+
+```text
+Claude Code hook
+  -> vge-cc-guard shim
+  -> Unix socket or Windows named pipe
+  -> vge-cc-guard daemon
+       -> local policy and session state
+       -> VGE scan when configured
+       -> allow, frame, quarantine, ask, or block
+       -> private audit/debug logs
+```
+
+The shim is a small per-hook process invoked by Claude Code. It lazy-starts one
+daemon per config directory. `PreToolUse` fails closed if the daemon cannot be
+reached. Non-critical events fail open unless the daemon already returned an
+explicit enforcement response.
+
+On macOS and Linux the daemon listens on a Unix socket. On Windows it listens
+on a named pipe. Private local files are hardened with POSIX modes on
+macOS/Linux and ACL tightening on Windows.
+
+## Hook Coverage
+
+| Hook | Behavior |
+|---|---|
+| `SessionStart` | Initializes local session state. |
+| `UserPromptSubmit` | Audits prompt receipt, resolves active control replies, scans prompt text and attachments, and blocks or asks before unsafe input reaches Claude. |
+| `PreToolUse` | Applies credential path protection, URL deny-list rules, session decisions, tainted-session policy, and per-tool gates. |
+| `PostToolUse` | Scans configured tool output, frames `SOFT_TAINT`, quarantines explicit VGE blocks, and handles fail-open scan failures. |
+| `SessionEnd` | Flushes state and clears active in-memory decisions for the session. |
+| `SubagentStart` / `SubagentStop` | Tracks subagent ownership for owner-scoped decisions and continuation prompts. |
+
+## PostTool Enforcement
+
+An explicit VGE block is any VGE result with one of:
+
+- `ruleAction: "BLOCK"`
+- `decision: "BLOCKED"`
+- `arbiterSignal: "BLOCK"`
+
+Explicit blocks are never converted to fail-open. The guard either asks for a
+decision or fails closed.
+
+For `WebSearch` and `WebFetch`, `SOFT_TAINT` uses a research-safe frame that
+tells Claude to continue the research task while treating retrieved content as
+untrusted, cross-checking claims, and ignoring instructions from retrieved
+content.
+
+When `policy.vge_failure_mode.posttool_output` is `fail_open`,
+`WebSearch`/`WebFetch` can use sidecar-local overload backpressure. A `429` or
+`5xx` VGE failure opens a short process-local cooldown. During that cooldown,
+matching research-tool outputs skip VGE, pass through fail-open, set the
+session to `caution`, and emit a distinct
+`posttool_output_scan_skipped_fail_open` audit event. Skipped outputs are not
+cached as VGE decisions.
+
+## Claude Code Contract Health
+
+`PostToolUse` L0 output replacement depends on Claude Code accepting
+`hookSpecificOutput.updatedToolOutput`. The daemon treats that as a live
+contract with the installed Claude Code binary. If the saved contract status is
+missing, stale, or tied to a different binary path/SHA/version, L0 replacement
+is disabled and PostTool HITL remains active through the safer degraded path.
+
+Check the current state with:
+
+```bash
+vge-cc-guard doctor
+vge-cc-guard daemon status
+vge-cc-guard config
+```
+
+The daemon status and TUI show the contract state, reason, Claude Code version,
+binary path, SHA prefix, live probe result, and next action. Unauthenticated
+`/health` does not expose this metadata.
+
+By default the daemon schedules a single background live probe when the
+contract is degraded and `policy.cc_contract.auto_probe_enabled` is `true`.
+The probe runs in a private temporary directory with a fixed Bash `printf`
+command and a temporary `PostToolUse` hook. L0 remains unavailable until the
+probe observes the expected replacement marker from the running Claude Code
+binary and writes `liveContract: "passed"` for the current path, version, and
+SHA.
+
+Relevant config defaults:
+
+| Field | Default |
+|---|---:|
+| `policy.cc_contract.auto_probe_enabled` | `true` |
+| `policy.cc_contract.auto_probe_timeout_ms` | `5000` |
+
+For unit and daemon lifecycle tests, `VGE_CC_GUARD_AUTO_PROBE_DISABLED=1`
+prevents the daemon from launching the live Claude Code probe while preserving
+the degraded runtime state.
+
+If auto-probe cannot run because Claude Code is not authenticated or the local
+CLI contract changed, run:
+
+```bash
+RUN_CC_LIVE=1 pnpm test tests/integration/cc-live-contract.test.ts
+```
+
+`vge-cc-guard doctor --cc-contract --assume-live-pass` is still available for
+controlled local recovery, but it is a manual trust override. Do not use it as
+evidence that a new Claude Code binary accepted `updatedToolOutput`.
+
+## Blocking Decisions
+
+Blocking decisions use stable `dec_*` IDs. Numeric shortcuts are accepted only
+when they can be routed unambiguously.
+
+Supported replies:
+
+```text
+1
+2
+3
+2 continue the task
+3 continue the task
+vge allow dec_<id> continue the task
+vge allow-session dec_<id> continue the task
+vge block dec_<id>
+```
+
+| Choice | Meaning |
+|---|---|
+| `1` / `block` | Keep the resource out of model context and record an exact-resource block. |
+| `2` / `allow once` | Allow one exact-resource retry. |
+| `3` / `allow for session` | Allow the exact resource until `SessionEnd`. |
+
+HITL decisions do not auto-expire while waiting for a human. They are cleared
+by a recorded decision, explicit reset, `SessionEnd`, daemon restart cleanup,
+or capacity eviction.
+
+## Quick Start
+
+Prerequisites:
+
+- Node.js `>=20.10.0`.
+- A reachable VGE instance.
+- A VGE API key.
+
+For an end-to-end walkthrough of every TUI screen, the block message formats,
+and common workflows, see [docs/USER_GUIDE.md](docs/USER_GUIDE.md).
+
+Install globally:
+
+```bash
+npm install -g @vigil-guard/vge-cc-guard      # latest stable
+npm install -g @vigil-guard/vge-cc-guard@beta # current beta
+vge-cc-guard install --apply --scope=user
+vge-cc-guard config
+```
+
+Install for one project:
+
+```bash
+cd /path/to/project
+vge-cc-guard install --dry-run --scope=project
+vge-cc-guard install --apply --scope=project
+vge-cc-guard config
+```
+
+Restart open Claude Code sessions after installing or changing hook settings.
+
+The installer writes hooks to Claude Code settings and preserves existing
+non-`vge-cc-guard` hooks.
+
+| Scope | Settings file |
+|---|---|
+| User | `~/.claude/settings.json` |
+| Project | `<project>/.claude/settings.json` |
+
+On Windows, user scope resolves under `%USERPROFILE%\.claude\settings.json`.
+
+## Configuration
+
+Open the TUI:
+
+```bash
+vge-cc-guard config
+```
+
+The main config file is:
+
+```text
+~/.vge-cc-guard/config.json
+```
+
+The TUI manages:
+
+- VGE API URL, client identity source, and API keys.
+- Per-tool `gate` and `analyze_output`.
+- IDE compatibility toggles for prompt text, prompt attachments, and subagent
+  output enforcement.
+- Per-stage VGE scan failure mode: `fail_closed` or `fail_open`.
+- Credential path protection.
+- URL Access Baseline presets and custom deny rules.
+- Read-only effective config export.
+
+Key defaults:
+
+| Area | Default |
+|---|---|
+| Credential protection | enabled |
+| Prompt text analysis | enforce |
+| Prompt attachment analysis | enforce |
+| Subagent output analysis | enforce |
+| VGE failure mode | fail closed for prompt text, attachments, and PostTool output |
+| PostTool overload backpressure | enabled, only active with PostTool fail-open and overload failures |
+| URL baseline | enabled; blocks cloud metadata and unsafe URL shapes |
+| Client identity | auto-detected OS username, sent as `metadata.clientId` |
+
+Full config semantics live in [docs/CONFIG_DESIGN.md](docs/CONFIG_DESIGN.md).
+
+The API Keys screen can set Client identity to Auto, Manual, or Disabled. Auto
+detects the logged-in OS username once per daemon process and sends it to VGE as
+`metadata.clientId`. Manual sends the stored `vge.client_id`. Disabled omits the
+field entirely.
+
+### VGE Connectivity Verification
+
+The API Keys screen verifies VGE connectivity through the local daemon control
+path, not from the TUI process directly:
+
+```text
+TUI -> local daemon -> VGE
+```
+
+This matches the process that handles hook traffic. The daemon checks the input
+key against `/v1/guard/input` and, when configured, the output key against
+`/v1/guard/analyze` with `source: "tool_output"`. If no output key is set, the
+TUI reports that output scans use the input key.
+
+Successful verification stores `vge.verified_at` plus endpoint and key
+fingerprints. Raw API keys are never written to the verification metadata.
+Changing the endpoint, input key, or output key makes the previous verification
+stale.
+
+`vge-cc-guard doctor` also prints VGE connectivity status and a next action
+when degraded.
+Use `vge-cc-guard doctor --no-vge` for a fast local-state check without a live
+VGE round-trip.
+
+## Default Tool Policy
+
+| Tool | Gate | Output analysis |
+|---|---:|---:|
+| `Bash` | `allow` | `true` |
+| `Read` | `allow` | `true` |
+| `Grep` | `allow` | `true` |
+| `Glob` | `allow` | `false` |
+| `WebSearch` | `allow` | `true` |
+| `WebFetch` | `allow` | `true` |
+| `Write` | `block` | `false` |
+| `Edit` | `block` | `false` |
+| `Task` | `allow` | `false` |
+| `*` | `ask` | `false` |
+
+`Task.analyze_output` remains `false` by default. Subagent-owned tool output is
+covered through owner metadata on the underlying tool hooks when
+`policy.subagent_output_analysis` is `enforce`.
+
+## Credential And URL Protection
+
+Credential path protection blocks sensitive local paths before content is read
+or sent to VGE. Examples include:
+
+- `.env` and `*.env`
+- `~/.ssh/*`
+- `~/.aws/credentials` and `~/.aws/config`
+- `~/.kube/config`
+- `~/.config/gcloud/*`, `~/.gcp/*`, and Windows gcloud config paths
+- private key filenames such as `id_rsa*` and `id_ed25519*`
+- filenames containing `credentials` or `secrets`
+
+URL Access Baseline checks are local and deterministic. Public URLs, localhost,
+loopback, and private LAN targets are allowed by default unless an enabled
+preset or custom deny rule matches. Cloud metadata endpoints, unsafe schemes,
+and URLs with embedded credentials are blocked by default.
+
+## Uninstall
+
+```bash
+vge-cc-guard uninstall --yes --scope=user
+vge-cc-guard uninstall --yes --scope=project
+vge-cc-guard uninstall --yes --project-dir /path/to/project
+```
+
+By default, uninstall preserves the current Claude Code settings file and
+removes only hook entries that invoke `vge-cc-guard hook`. Use `--restore` to
+replace `settings.json` with the install-time backup. Global state under
+`~/.vge-cc-guard/` is removed only after the last install record is gone.
+
+## Commands
+
+```bash
+vge-cc-guard install --apply --scope=user
+vge-cc-guard install --apply --scope=project
+vge-cc-guard install --dry-run
+
+vge-cc-guard uninstall --yes --scope=user
+vge-cc-guard uninstall --yes --scope=project
+vge-cc-guard uninstall --yes --scope=user --restore
+
+vge-cc-guard config
+vge-cc-guard reset-session
+vge-cc-guard daemon
+vge-cc-guard daemon status
+vge-cc-guard daemon reload
+vge-cc-guard daemon stop
+vge-cc-guard doctor --cc-contract
+vge-cc-guard hook <event>
+```
+
+`hook` is called by Claude Code. Do not run it manually unless testing hook
+payload handling.
+
+## Audit And Metrics
+
+Audit records are written as private JSONL under:
+
+```text
+~/.vge-cc-guard/audit.log
+```
+
+Audit records include decision IDs, session IDs, owner metadata, stage,
+outcome, resolver source, synthesized source, latency, and VGE or local
+fallback metadata. Raw prompt text, raw tool output, full URLs with query
+strings, and API keys are not written to audit.
+
+The daemon also exposes an authenticated local metrics snapshot:
+
+```text
+POST /v1/control/decision-metrics
+```
+
+## IDE Notes
+
+Terminal Claude Code supports the full HITL loop. Native IDE panels, including
+VS Code Claude Code surfaces, may not reliably show prompt text or attachment
+decision prompts. For guarded prompt/attachment work, use terminal Claude Code.
+
+For IDE-native usage, consider:
+
+```text
+IDE Compatibility -> Prompt text -> off
+IDE Compatibility -> Prompt file attachments -> off
+```
+
+In `off` mode, the guard still scans and audits those ingress paths, but it
+does not create blocking decisions for them. Credential path protection still
+applies.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| `vge-cc-guard config` prints permission denied after local build | Run `pnpm build`; local `npm link` needs `dist/cli.js` executable on POSIX. |
+| Tool is always blocked | Open `vge-cc-guard config` and review Tools Policy. |
+| Credential path is denied | Review `policy.credential_protection`; it is enabled by default. |
+| No VGE events | Check API URL/key in `vge-cc-guard config`, then `~/.vge-cc-guard/debug.log`. PreTool URL baseline decisions are local. |
+| Daemon will not start | Run `vge-cc-guard daemon` in the foreground and check Node.js version. |
+| Claude Code GUI cannot find `vge-cc-guard` | GUI apps may not inherit shell `PATH`; install with an absolute hook command path. |
+| Session state seems stuck | Run `vge-cc-guard reset-session`. |
+| PostTool replacement is refused | Run `vge-cc-guard doctor --cc-contract`. |
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm test:coverage
+```
+
+Useful local loop:
+
+```bash
+pnpm build
+npm link
+vge-cc-guard install --dry-run --scope=project
+vge-cc-guard daemon
+```
+
+For Windows-sensitive changes, run the CI matrix and the checklist in
+[docs/testing/windows-smoke.md](docs/testing/windows-smoke.md).
+
+## References
+
+- [User Guide](docs/USER_GUIDE.md)
+- [Architecture](docs/architecture/claude-code-agent-security-integration.md)
+- [TUI design and config reference](docs/CONFIG_DESIGN.md)
+- [PRD_1](docs/prd/PRD_1/PRD_1.md)
+- [PRD_17](docs/prd/PRD_17/PRD_17.md) — PostTool overload backpressure
+- [PRD_18](docs/prd/PRD_18/PRD_18.md) — Claude Code contract auto-probe
+- [PRD_19](docs/prd/PRD_19/PRD_19.md) — VGE connectivity verification through daemon
+- [ADR-0007](docs/adr/ADR-0007-claude-code-contract-auto-probe.md)
+- [ADR index](docs/adr/)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { installSystemCAs } from './shared/system-ca.js';
+installSystemCAs();
+const command = process.argv[2];
+const usage = `
+vge-cc-guard <command>
+
+Commands:
+  install        Register hooks in Claude Code settings
+  uninstall      Remove installed hooks for user/project scope.
+                   Flags: --yes (required), --scope=user|project, --project-dir <path>, --restore.
+                   Default preserves current Claude Code settings and removes only vge-cc-guard hooks.
+                   --restore replaces settings.json with the install-time backup.
+                   Global state is removed only when the last install is uninstalled.
+  config         Open TUI configurator
+  hook <event>   Handle a Claude Code hook event (called by CC, not the user)
+  daemon         Start the daemon in foreground, or run daemon status|reload|stop|restart
+  doctor         Run local diagnostics. Flags: --cc-contract
+  reset-session  Clear session allow/block decisions and legacy pending state
+`.trim();
+switch (command) {
+    case 'hook': {
+        const { main } = await import('./shim/index.js');
+        await main();
+        break;
+    }
+    case 'daemon': {
+        const { runDaemonCommand } = await import('./commands/daemon.js');
+        await runDaemonCommand(process.argv.slice(3));
+        break;
+    }
+    case 'install': {
+        const { runInstall } = await import('./commands/install.js');
+        await runInstall(process.argv.slice(3));
+        break;
+    }
+    case 'uninstall': {
+        const { runUninstall } = await import('./commands/uninstall.js');
+        await runUninstall(process.argv.slice(3));
+        break;
+    }
+    case 'reset-session': {
+        const { runResetSession } = await import('./commands/reset-session.js');
+        await runResetSession();
+        break;
+    }
+    case 'doctor': {
+        const { runDoctor } = await import('./commands/doctor.js');
+        await runDoctor(process.argv.slice(3));
+        break;
+    }
+    case 'config': {
+        const { runConfig } = await import('./commands/config.js');
+        await runConfig();
+        break;
+    }
+    default:
+        console.log(usage);
+        process.exit(command === '--help' || command === '-h' ? 0 : 1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,gBAAgB,EAAE,CAAC;AAEnB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;CAeb,CAAC,IAAI,EAAE,CAAC;AAET,QAAQ,OAAO,EAAE,CAAC;IAChB,KAAK,MAAM,CAAC,CAAC,CAAC;QACZ,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACjD,MAAM,IAAI,EAAE,CAAC;QACb,MAAM;IACR,CAAC;IACD,KAAK,QAAQ,CAAC,CAAC,CAAC;QACd,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAClE,MAAM,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,MAAM;IACR,CAAC;IACD,KAAK,SAAS,CAAC,CAAC,CAAC;QACf,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;QAC7D,MAAM,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM;IACR,CAAC;IACD,KAAK,WAAW,CAAC,CAAC,CAAC;QACjB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACjE,MAAM,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,MAAM;IACR,CAAC;IACD,KAAK,eAAe,CAAC,CAAC,CAAC;QACrB,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;QACxE,MAAM,eAAe,EAAE,CAAC;QACxB,MAAM;IACR,CAAC;IACD,KAAK,QAAQ,CAAC,CAAC,CAAC;QACd,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAC3D,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM;IACR,CAAC;IACD,KAAK,QAAQ,CAAC,CAAC,CAAC;QACd,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAC3D,MAAM,SAAS,EAAE,CAAC;QAClB,MAAM;IACR,CAAC;IACD;QACE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/commands/_lib/install-paths.d.ts

@@ -0,0 +1,16 @@
+export type InstallScope = 'user' | 'project';
+export interface InstallBackupMetadata {
+    scope: InstallScope;
+    settingsPath: string;
+    installedAt: string;
+}
+export declare function resolveVgeDir(): string;
+export declare function resolveCwd(): string;
+export declare function resolveProjectDir(projectDir?: string): string;
+export declare function resolveClaudeDir(scope: InstallScope, projectDir?: string): string;
+export declare function resolveSettingsPath(scope: InstallScope, projectDir?: string): string;
+export declare function installsDir(): string;
+export declare function installKey(settingsPath: string): string;
+export declare function backupPath(settingsPath: string): string;
+export declare function metaPath(settingsPath: string): string;
+//# sourceMappingURL=install-paths.d.ts.map

package/dist/commands/_lib/install-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-paths.d.ts","sourceRoot":"","sources":["../../../src/commands/_lib/install-paths.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAMnC;AAED,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ7D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/commands/_lib/install-paths.js

@@ -0,0 +1,46 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+export function resolveVgeDir() {
+    return process.env['VGE_CC_GUARD_CONFIG_DIR'] ?? path.join(os.homedir(), '.vge-cc-guard');
+}
+export function resolveCwd() {
+    try {
+        return process.cwd();
+    }
+    catch {
+        throw new Error('vge-cc-guard: current working directory no longer exists. Pass --project-dir <path>.');
+    }
+}
+export function resolveProjectDir(projectDir) {
+    const input = projectDir ?? resolveCwd();
+    const absolute = path.resolve(input);
+    try {
+        return fs.realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+export function resolveClaudeDir(scope, projectDir) {
+    if (scope === 'project')
+        return path.join(resolveProjectDir(projectDir), '.claude');
+    return process.env['CLAUDE_CONFIG_HOME'] ?? path.join(os.homedir(), '.claude');
+}
+export function resolveSettingsPath(scope, projectDir) {
+    return path.join(resolveClaudeDir(scope, projectDir), 'settings.json');
+}
+export function installsDir() {
+    return path.join(resolveVgeDir(), 'installs');
+}
+export function installKey(settingsPath) {
+    return crypto.createHash('sha256').update(settingsPath).digest('hex').slice(0, 16);
+}
+export function backupPath(settingsPath) {
+    return path.join(installsDir(), `${installKey(settingsPath)}.backup.json`);
+}
+export function metaPath(settingsPath) {
+    return path.join(installsDir(), `${installKey(settingsPath)}.meta.json`);
+}
+//# sourceMappingURL=install-paths.js.map

package/dist/commands/_lib/install-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-paths.js","sourceRoot":"","sources":["../../../src/commands/_lib/install-paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAU7B,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,sFAAsF,CAAC,CAAC;IAC1G,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,UAAmB;IACnD,MAAM,KAAK,GAAG,UAAU,IAAI,UAAU,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAmB,EAAE,UAAmB;IACvE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC;IACpF,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAmB,EAAE,UAAmB;IAC1E,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,eAAe,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,UAAU,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,YAAoB;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,UAAU,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;AAC3E,CAAC"}

package/dist/commands/_lib/parse-install-flags.d.ts

@@ -0,0 +1,8 @@
+export type InstallScope = 'user' | 'project';
+export type InstallMode = 'apply' | 'dry-run' | 'wizard';
+export interface InstallFlags {
+    scope: InstallScope;
+    mode: InstallMode;
+}
+export declare function parseInstallFlags(args: readonly string[]): InstallFlags;
+//# sourceMappingURL=parse-install-flags.d.ts.map

package/dist/commands/_lib/parse-install-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-install-flags.d.ts","sourceRoot":"","sources":["../../../src/commands/_lib/parse-install-flags.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;AAC9C,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,CAUvE"}

package/dist/commands/_lib/parse-install-flags.js

@@ -0,0 +1,15 @@
+export function parseInstallFlags(args) {
+    // `--project` is the Phase 1c shorthand for `--scope=project --apply`.
+    // Explicit flags (--apply/--dry-run) keep their existing precedence over
+    // each other; --project's implicit apply only kicks in if neither is set.
+    const projectAlias = args.includes('--project');
+    const scope = projectAlias || args.includes('--scope=project') ? 'project' : 'user';
+    if (args.includes('--apply'))
+        return { scope, mode: 'apply' };
+    if (args.includes('--dry-run'))
+        return { scope, mode: 'dry-run' };
+    if (projectAlias)
+        return { scope, mode: 'apply' };
+    return { scope, mode: 'wizard' };
+}
+//# sourceMappingURL=parse-install-flags.js.map

package/dist/commands/_lib/parse-install-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-install-flags.js","sourceRoot":"","sources":["../../../src/commands/_lib/parse-install-flags.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,iBAAiB,CAAC,IAAuB;IACvD,uEAAuE;IACvE,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,KAAK,GAAiB,YAAY,IAAI,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IAClG,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC9D,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAClE,IAAI,YAAY;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAClD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACnC,CAAC"}

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+export declare function runConfig(): Promise<void>;
+//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.tsx"],"names":[],"mappings":"AAOA,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAqC/C"}