@contextecf/guardian-cli 0.1.0

package/README.md

@@ -0,0 +1,218 @@
+# Project Guardian CLI
+
+Project Guardian is a local-first Personal Context Fabric for AI prompt
+governance, local receipts, policy packs, MCP tools, and browser prompt checks.
+
+## One-Line Install
+
+Install the CLI globally, CodeLedger-style:
+
+```bash
+npm install -g @contextecf/guardian-cli
+guardian setup
+```
+
+Then open the Control Tower in your default browser:
+
+```bash
+guardian launch
+```
+
+The same daemon-backed launch path is also available as:
+
+```bash
+guardian tower
+guardian control-tower
+```
+
+Or run setup without a global install:
+
+```bash
+npx @contextecf/guardian-cli@latest setup
+```
+
+The installed binary is `guardian`.
+
+Guardian CLI requires Node.js 22 or newer. The release clean-room install smoke
+uses a Node 22 trixie Docker image so native SQLite dependencies are tested
+against the same Node and Linux glibc floor expected for public npm users.
+
+## First Run
+
+```bash
+guardian setup
+guardian doctor
+guardian readiness
+guardian launch
+guardian status
+guardian open
+guardian policy list
+guardian marketplace list
+guardian posture list
+guardian preferences show
+guardian privacy show
+guardian mcp install
+guardian daemon pair --json
+guardian desktop execute --input=/path/to/approved-action.json --yes
+```
+
+`guardian setup` is the one-command first-run path after `npm install -g` or
+through `npx`. It creates or reuses the local profile, keeps local-first privacy
+defaults, runs doctor/data checks, writes Guardian-owned MCP snippets under the
+Guardian profile directory, starts or reuses the local daemon, opens the Control
+Tower unless `--print` is supplied, and returns browser-extension setup guidance
+without printing the runtime token. It does not install the native host manifest
+or write external AI tool config unless the user runs the explicit follow-up
+commands.
+
+`guardian extension native-host install --extension-id=<id>` writes the
+Guardian browser native messaging helper and manifest. On macOS/Linux it writes
+the browser manifest path directly. On Windows it writes the helper, `.cmd`
+launcher, and manifest under `GUARDIAN_HOME/native-host`, then prints exact HKCU
+`reg add`/`reg delete` commands for reviewed registration. Windows users can run
+`guardian extension native-host install --extension-id=<id> --write-registry
+--yes` to perform the HKCU registration through argv-based `reg add` and write a
+token-free proof that `guardian extension native-host status --json` can verify.
+
+`guardian launch`, `guardian tower`, and `guardian control-tower` start or reuse
+the local daemon and then open the Control Tower in the default browser. During
+the MVP, that daemon exposes a lightweight metadata-only status page at the
+default URL. Re-running `guardian launch`, `guardian tower`,
+`guardian control-tower`, or `guardian start` first checks the requested
+authenticated loopback health endpoint and reuses the existing daemon when it is
+already reachable. Use `guardian daemon serve` when you want the foreground
+developer process instead. Use `guardian launch --print`,
+`guardian tower --print`, or `guardian control-tower --print` to print the URL
+without opening a browser.
+
+`guardian open` launches the already configured local Control Tower URL in the
+default browser without starting the daemon. It uses the installed
+profile/default loopback URL unless supplied with a loopback URL through `--url`
+or `GUARDIAN_CONTROL_TOWER_URL`; it refuses non-loopback URLs.
+
+`guardian stop` sends an authenticated local loopback request to the running
+daemon and then marks the runtime stopped in the local profile. It does not
+print the runtime token and it refuses non-loopback stop URLs.
+
+`guardian status` reports whether Guardian is installed, which Control Tower URL
+is configured, and whether the daemon answers an authenticated local health
+probe. It never prints the local runtime token.
+
+`guardian readiness` separates the CodeLedger-style npm preview install path
+from the full production release claim. It reports npm preview readiness from
+the protected package evidence and npm publish dry-run, while keeping full
+production release blocked until signed native installers, browser-store
+distribution, high-risk desktop action execution, and autonomous local app execution
+are proven. SQLite page-level encryption is proven for the local
+Personal ECL store when `GUARDIAN_SQLITE_PAGE_ENCRYPTION_KEY` is configured.
+Use `guardian readiness --strict`
+in operator automation when the command should exit nonzero unless both preview
+and full production claims are ready.
+
+The daemon-served Control Tower includes a Release & Doctor section that mirrors
+the local `guardian doctor` and `guardian status` evidence: doctor pass/warn/fail
+counts, protected release evidence status, package metadata, checksum count, and
+source/source-map/workspace-runtime-import boundary state. It remains
+metadata-only and does not expose the runtime token.
+
+`guardian privacy show` reports the local-first privacy posture, including
+metadata-only defaults, raw content capture, cloud sync, local app autopilot,
+receipt raw-content state, and pending encryption-at-rest controls. It never
+prints the local runtime token.
+
+`guardian key-store install --yes` stores a Guardian local-data key through the
+platform OS credential store using stdin-only secret input: macOS Keychain,
+Windows DPAPI, or Linux Secret Service. `guardian key-store status`,
+`guardian data status`, `guardian privacy show`, and `guardian doctor` surface
+only token/key-free proof metadata.
+
+`guardian policy list`, `guardian policy enable <pack-id>`, and
+`guardian policy disable <pack-id>` let users manage preset policy packs after
+install. Guardian persists the active selection in `profile.json` and
+`policy-packs.json`, rejects unknown pack IDs, and keeps at least one pack
+active so the local runtime does not accidentally run without guardrails.
+
+`guardian marketplace list`, `guardian marketplace show <pack-id>`, and
+`guardian marketplace submit-template --json` expose the first browse-only
+Policy Pack Marketplace metadata surface. Users and administrators can inspect
+publisher, distribution class, review status, compatibility, price/license,
+proven/not-proven claims, limitations, and custom-pack submission shape before
+connecting anything. Marketplace packs cannot bypass Guardian's local policy
+engine, confirmation gates, provider/source/app revocations, or receipts.
+
+`guardian posture list` and `guardian posture set
+<calm|balanced|guided|high_assurance|autopilot_lite>` let users manage the
+superordinate Guardian Posture Profile above individual policy packs and
+preferences. Guardian persists the selected profile in `profile.json` and
+`posture-profile.json`, shows the behavior preview in Control Tower, and does
+not silently enable raw capture, cloud sync, or local app autopilot.
+
+`guardian preferences show`, `guardian preferences coach
+<off|quiet|balanced|hands_on>`, and `guardian preferences learning <on|off>`
+let users decide how often Prompt Coach should tag along and whether the local
+Learning Graph is enabled. Guardian persists these choices in `profile.json`
+and `preferences.json`; Prompt Coach opt-out is honored by the local daemon
+without disabling policy checks.
+
+`guardian install`, `guardian doctor`, and `guardian mcp install` do not print
+the local runtime token. The token is emitted only by the explicit
+`guardian daemon pair --json` handoff command so the browser extension can be
+paired deliberately.
+
+`guardian desktop execute --input=/path/to/approved-action.json --yes` is the
+first conservative desktop adapter. It consumes an approved MCP local-action
+response, verifies the desktop execution plan hash, requires a second local
+confirmation flag, refuses high-risk action types, opens only bounded
+`http://` or `https://` URL targets in the MVP, emits the
+`guardian_desktop_url_open` adapter id/version/capability proof, and writes a
+metadata-only Personal ECL receipt. It does not execute
+send/delete/pay/publish/system-change actions.
+
+`guardian desktop safety-smoke --json` is the release-readiness smoke for this
+surface. It keeps local app autopilot off, blocks a high-risk send action
+before adapter invocation, exercises the bounded low-risk desktop-browser open
+adapter path with a simulated open, and emits token-safe metadata-only receipt
+and event-chain evidence. It does not authorize autopilot or close a production
+gate.
+
+## Privacy Defaults
+
+Guardian starts local-first:
+
+- raw content capture off
+- cloud sync off
+- learning graph opt-in
+- local app autopilot off
+- metadata-only receipts by default
+
+## Package Boundary
+
+The npm package publishes bundled CLI/runtime JavaScript, TypeScript
+declarations, and this README. Guardian workspace packages are bundled into the
+CLI entrypoints so `npx @contextecf/guardian-cli@latest setup` can run outside
+the monorepo. The native SQLite adapter remains a normal `better-sqlite3`
+runtime dependency.
+
+Source files, source maps, and source-controlled release gates remain in the
+private repository and should be validated before broad distribution.
+
+Release operators can run `npm run guardian:release:doctor` from the repo root
+for the complete protected-release doctor before publishing. For a release
+candidate artifact, set `GUARDIAN_RELEASE_CANDIDATE=/path/to/artifact.zip` and
+run `npm run guardian:release:audit`; the audit runs the same doctor and scans
+the candidate with the protected IP scanner. The audit also honors
+`GUARDIAN_RELEASE_CLAIM`; it defaults to `preview`, while
+`GUARDIAN_RELEASE_CLAIM=production` fails until every not-proven production gate
+is closed in release evidence. Before npm publication, run
+`npm run guardian:npm:publish:dry-run` to exercise
+`npm publish --dry-run --json` against the packed Guardian CLI tarball and add
+that result to the npm package evidence. For the final pre-publish operator
+gate, run `npm run guardian:npm:publish:ready`; it repeats the protected npm
+doctor with the dry-run enabled, records readiness evidence, and prints the
+exact `npm publish <tarball> --access public` command without executing it.
+
+When an installed profile contains `release/release-evidence.json`,
+`guardian doctor` verifies the protected package evidence schema, expected-file
+allowlist, source/source-map exclusions, unpublished workspace import boundary,
+and checksum manifest. `guardian status --json` surfaces the same
+metadata-only release-evidence state without printing runtime tokens.

package/dist/packages/guardian-cli/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};