@amityco/social-plus-vise 0.4.0 → 0.8.0

package/README.md

@@ -1,92 +1,330 @@
-# Vise Skill and CLI
+<p align="center">
+  <img src="./social.plus-vise.png" alt="social.plus Vise" width="320" />
+</p>
 
-This package provides deterministic local tooling for social.plus SDK integration assistance.
+<h1 align="center">social.plus Vise</h1>
 
-The bundled skill is the AI workflow layer. It tells host agents how to move from user intent to inspect, plan, docs grounding, edits, validation, and sensor runs.
+<p align="center">
+  <strong>The standards harness that keeps AI coding agents on the rails when integrating social.plus SDKs.</strong>
+</p>
 
-The CLI is the deterministic execution layer. It can inspect repositories, detect design/theme signals, search hosted docs, plan harness guides/sensors, produce grounded integration plans with structured intake questions, validate setup patterns, and run detected project sensors.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@amityco/social-plus-vise"><img src="https://img.shields.io/npm/v/@amityco/social-plus-vise.svg" alt="npm version" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Proprietary-blue.svg" alt="License" /></a>
+  <a href="https://learn.social.plus"><img src="https://img.shields.io/badge/Docs-learn.social.plus-informational" alt="Docs" /></a>
+</p>
 
-Vise is shipped locally because SDK implementation quality depends on both hosted social.plus docs and the customer's local project context. Local execution lets Vise inspect manifests, app surfaces, design tokens, lifecycle code, and constrained command sensors while keeping source code on the customer's machine.
+<p align="center">
+  <code>npm install -g @amityco/social-plus-vise</code>
+</p>
 
-The stdio MCP server is an optional compatibility adapter over the same CLI-backed operations for MCP-capable tools. It is not the primary workflow layer.
+---
 
-Frequent customer paths have dedicated guardrails:
+## Quick Start
 
-- feed and post creation: concrete feed target, no invented communityId/targetId/feedId, no inline API keys
-- secrets: never request API keys or credentials in chat; create env/config placeholders and have the user fill real values locally
-- notification setup: platform credentials, token source, registration after login, unregister on logout/user switch
-- Live Objects/Collections: object vs collection, observed domain, lifecycle owner, loading/error states, cleanup
-- monorepos: detected app surfaces can be selected with `surfacePath`
+```sh
+# 1. Install
+npm install -g @amityco/social-plus-vise
+
+# 2. Install the AI skill into your coding tool (pick your host)
+vise install-skill --target claude        # Claude Code (personal)
+vise install-skill --target cursor .      # Cursor (project-local)
+vise install-skill --target copilot .     # GitHub Copilot / VS Code
+
+# 3. Inside your project, let your AI agent run the Vise loop
+cd your-app
+vise inspect                              # detect platform, surface, design signals
+vise plan --request "Add a social feed"   # produce a grounded implementation plan
+vise init --request "Add a social feed"   # write the sp-vise/ compliance contract
+
+# 4. After the agent makes edits
+vise check                                # verify the integration against the contract
+vise run-sensors                          # run your project's own build/typecheck/lint
+```
+
+That's it. The skill at `skills/social-plus-vise/SKILL.md` (installed in step 2) teaches your AI agent when to run each command. Skip to [Usage Flow](#usage-flow) for the full picture.
+
+---
+
+## What Vise Does
+
+Vise is a **local CLI + AI skill** that wraps coding agents in deterministic compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 250+ platform-specific compliance rules, and runs your project's own build/lint/typecheck sensors — all locally. **Your source code never leaves your machine.**
 
-`run_sensors` is constrained to detected project commands. It does not accept arbitrary shell input.
+| Layer | Purpose |
+|---|---|
+| **Skill** (`SKILL.md`) | Tells your AI agent when to inspect, plan, fetch docs, edit, validate, and attest |
+| **CLI** (`vise`) | Deterministic engine: inspects repos, searches docs, validates setup, runs sensors, manages attestations |
+| **MCP adapter** | Optional stdio server for MCP-capable tools (Claude Code, Cursor, Codex, VS Code, Copilot) |
 
-## Commands
+### Why "Vise"
 
-Install Vise globally:
+A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Without one, the workpiece drifts and cuts wander. Vise does the same for AI agents integrating SDKs: it clamps the integration to a known-good position (the real docs, the real project structure, the real compliance rules) so the agent can focus on creative work instead of guessing.
+
+---
+
+## Supported Platforms
+
+| Platform | Coverage | Sensors |
+|---|---|---|
+| **TypeScript / Next.js / React** | ✅ Full | `tsc`, `npm build`, `npm lint`, SDK import smoke |
+| **React Native** | ✅ Full | `tsc`, `npm lint`, SDK import smoke |
+| **Flutter / Dart** | ✅ Full | `flutter analyze`, `flutter test` |
+| **Android (Kotlin)** | ✅ Full | Gradle assemble, unit tests |
+| **iOS (Swift)** | ✅ Full | (static rule checks; runtime sensors WIP) |
+
+Each platform has 50–55 rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).
+
+---
+
+## Installation
+
+### Install the CLI
 
 ```sh
 npm install -g @amityco/social-plus-vise
-vise doctor
+vise doctor                                # verify install
 ```
 
-Local development:
+Or install per-project:
 
 ```sh
-npm install
-npm run build
-npm start
+npm install -D @amityco/social-plus-vise
+npx vise --help
 ```
 
-CLI:
+### Install the Skill Into Your Coding Tool
 
-```sh
-vise doctor
-vise install-skill --target codex
-vise install-skill --target claude
-vise install-skill --target claude-project .
-vise install-skill --target agents .
-vise install-skill --target cursor .
-vise install-skill --target vscode .
-vise install-skill --target copilot .
-vise print-skill
-vise search-docs "create post"
-vise get-doc-page social-plus-sdk/social/content-management/posts/creation/text-post
-vise inspect
-vise plan-harness --request "Add a social feed"
-vise plan --request "Add a social feed"
-vise init --request "Add a social feed"
-vise check
-vise sync
-vise attest --rule typescript.client.region --confidence high --signer host-agent --evidence-file evidence.json --rationale "..."
-vise explain typescript.client.region
-vise status
-vise engagement init --tier pro --customer-id acme --scope add-feed,setup-push
-vise engagement show
-vise validate
-vise run-sensors --dry-run
-vise mcp
+The skill is what teaches your AI agent how to use Vise. Pick the matching host:
+
+| Host | Install command |
+|---|---|
+| Claude Code (personal scope) | `vise install-skill --target claude` |
+| Claude Code (project scope) | `vise install-skill --target claude-project .` |
+| OpenAI Codex | `vise install-skill --target codex` |
+| Cursor (native skills) | `vise install-skill --target cursor .` |
+| Cursor (legacy rules) | `vise install-skill --target cursor-rules .` |
+| GitHub Copilot / VS Code | `vise install-skill --target vscode .` |
+| Copilot CLI / project | `vise install-skill --target copilot .` |
+| Generic agent project | `vise install-skill --target agents .` |
+| Other coding agents | `vise print-skill` (paste output into the host's project instructions) |
+
+The skill is plain Markdown; you can read it any time with `vise print-skill`.
+
+---
+
+## Usage Flow
+
+```mermaid
+flowchart LR
+    A[User asks AI agent<br/>'Add a social feed'] --> B[Agent runs<br/>vise inspect]
+    B --> C[Agent runs<br/>vise plan --request &quot;...&quot;]
+    C --> D{Intake<br/>questions?}
+    D -->|Yes| E[Agent asks user<br/>for feed target,<br/>design source, etc.]
+    D -->|No| F
+    E --> F[Agent runs<br/>vise init]
+    F --> G[Agent runs<br/>vise search-docs<br/>vise get-doc-page]
+    G --> H[Agent edits<br/>your code]
+    H --> I[Agent runs<br/>vise check]
+    I --> J{Green?}
+    J -->|No, fixable| K[Agent fixes<br/>findings]
+    K --> I
+    J -->|No, attest| L[Agent calls<br/>vise attest with<br/>evidence]
+    L --> I
+    J -->|Yes| M[Agent runs<br/>vise run-sensors]
+    M --> N[Done.<br/>sp-vise/ contract<br/>committed]
 ```
 
-Bundled skill guidance ships in `skills/social-plus-vise/SKILL.md` for coding tools that support Agent Skills or instruction-pack installation. Use `vise install-skill --target codex`, `vise install-skill --target claude`, `vise install-skill --target claude-project .`, `vise install-skill --target agents .`, `vise install-skill --target cursor .`, `vise install-skill --target vscode .`, `vise install-skill --target copilot .`, or `vise print-skill`. The Cursor target installs native project skills under `.cursor/skills`; the VS Code and Copilot targets install native project skills under `.github/skills`; `--target cursor-rules` remains available for Cursor project-rule fallback installs.
+The flow above is what the skill teaches your AI agent. You — the human — drive intent and approve edits; the agent runs Vise commands deterministically; Vise grounds the agent in real docs and real compliance rules.
 
-Full local validation:
+---
 
-```sh
-npm run validate
+## CLI Reference
+
+### Project inspection and planning
+
+| Command | Purpose |
+|---|---|
+| `vise doctor` | Verify install; print version, install path, docs source |
+| `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
+| `vise plan [path] --request "..."` | Produce a grounded implementation plan with intake questions and docs citations |
+| `vise plan-harness [path] --request "..."` | (Pre-planning step) Build the harness around the request |
+| `vise init [path] --request "..."` | Write the `sp-vise/` compliance contract for this project |
+
+### Documentation grounding
+
+| Command | Purpose |
+|---|---|
+| `vise search-docs "<query>"` | Search social.plus docs for relevant pages |
+| `vise get-doc-page <path>` | Fetch a specific doc page by path |
+
+### Compliance verification
+
+| Command | Purpose |
+|---|---|
+| `vise check [path]` | Re-validate against the recorded contract; reports `green`, `needs-attestation`, `deterministic-failures`, `blocked`, or `contract-drift` |
+| `vise check [path] --ci` | Same as `check`, but read-only and exits non-zero unless green (for CI pipelines) |
+| `vise validate [path]` | Run the deterministic validators (subset of `check` that doesn't compare against attestations) |
+| `vise sync [path]` | Persist deterministic-pass evidence to `sp-vise/attestations/` |
+| `vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..."` | Record an attestation when a rule passes through customer-specific architecture that the deterministic check can't see |
+| `vise explain <ruleId>` | Print the rule's rationale, evidence requirements, and remediation guidance |
+| `vise status [path]` | Summarize the current compliance state |
+
+### Sensors
+
+| Command | Purpose |
+|---|---|
+| `vise run-sensors [path]` | Run detected project commands (npm scripts, Gradle, Flutter, lint, typecheck, SDK import smokes); never executes arbitrary shell |
+| `vise run-sensors [path] --dry-run` | List what would run without executing |
+
+### Skill management
+
+| Command | Purpose |
+|---|---|
+| `vise install-skill --target <host>` | Install the bundled skill into a coding host (see [Installation](#installation)) |
+| `vise print-skill` | Print the skill markdown to stdout |
+
+### Engagement scope (optional contractual metadata)
+
+| Command | Purpose |
+|---|---|
+| `vise engagement init [path] [--tier ...] [--customer-id ...] [--scope ...]` | Record the contractual scope for this integration |
+| `vise engagement show [path]` | Print the recorded engagement metadata |
+
+### MCP server
+
+| Command | Purpose |
+|---|---|
+| `vise mcp` | Start the stdio MCP compatibility adapter |
+
+---
+
+## MCP Integration
+
+MCP-capable hosts can call Vise as structured tool calls instead of shell commands.
+
+### Config
+
+```json
+{
+  "mcpServers": {
+    "social-plus": {
+      "command": "vise",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
-Product-oriented Vise improvement discovery:
+### Tool names (snake_case per MCP convention)
 
-```sh
-npm run test:improvements
+`inspect_project`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `search_docs`, `get_doc_page`, `validate_setup`, `run_sensors`.
+
+These are the same operations as the CLI commands above, exposed as MCP tools.
+
+---
+
+## CI Compliance
+
+Add `vise check --ci` to your CI pipeline after committing `sp-vise/compliance.json` to your repository:
+
+```yaml
+name: Vise Compliance
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  vise-compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install -g @amityco/social-plus-vise
+      - run: vise check . --ci
 ```
 
-## Docs Source
+**Exit codes:**
+
+| Code | Meaning |
+|---|---|
+| `0` | All rules pass (deterministic or attested) |
+| `1` | One or more rules need attestation |
+| `2` | One or more rules have deterministic failures |
+| `3` | One or more blockers fired (missing prerequisite, e.g. `google-services.json`) |
+| `4` | Contract drift — rules in `sp-vise/compliance.json` no longer match the current ruleset |
+
+`vise check --ci` is read-only. It never updates `sp-vise/`. The JSON output includes a `ci` block with structured details for pipeline logs.
+
+---
+
+## Compliance Contract
+
+After `vise init`, your project gets a `sp-vise/` directory. These files become part of your repo and travel through code review:
+
+| File | Created by | What it contains |
+|---|---|---|
+| `sp-vise/compliance.json` | `vise init` | The rules selected for this integration, the Vise version, the ruleset digest, the target app surface, and an optional engagement link. |
+| `sp-vise/attestations/*.json` | `vise sync` (deterministic) or `vise attest` (host-agent / human) | Per-rule evidence: signer, confidence, rationale, cited files (with source fingerprints for drift detection). |
+| `sp-vise/inspection.json` | `vise init` | The platform, monorepo surface, and design-token signals detected at init time. |
+| `sp-vise/engagement.json` | `vise engagement init` (optional) | Contractual scope: tier, customer ID, contracted outcomes, reviewer assignment. |
 
-By default, docs are read from:
+**Commit `sp-vise/` to your repo.** `vise check` re-validates against the recorded contract on every run, comparing current code against the recorded attestations. If code changes and breaks a rule, the next `check` reports `deterministic-fail`, `attestation-needed`, or `blocked` — never a silent regression.
 
-```text
-https://learn.social.plus/llms-full.txt
+If a rule passes through customer-specific architecture the validator can't see (a DI wrapper, an unconventional file layout, etc.), record an attestation:
+
+```sh
+vise attest . \
+  --rule typescript.client.region \
+  --signer host-agent \
+  --confidence high \
+  --evidence-file evidence.json \
+  --rationale "Region is read from NEXT_PUBLIC_AMITY_REGION env var in lib/amity.ts:6"
 ```
 
-Maintainers can set `SOCIAL_PLUS_DOCS_ROOT` to test against a local `social-plus-docs` checkout.
+Attestation files record source fingerprints (SHA-256 of cited files) so subsequent edits invalidate stale attestations.
+
+---
+
+## Benchmark Headline
+
+| Platform | Pure MCP findings | Vise findings | Pure MCP CI | Vise CI |
+|---|---|---|---|---|
+| React / Next.js | 7 (3 errors) | 2 (warnings) | ❌ FAIL | ✅ PASS |
+| React Native | 6 | 2 | ❌ FAIL | ✅ PASS |
+| Flutter | 9 | 2 | ❌ FAIL | ✅ PASS |
+| Android (Kotlin) | 9 | 0 | ❌ FAIL | ✅ PASS |
+| iOS (Swift) | 8 | 0 | ❌ FAIL | ✅ PASS |
+
+Measured runs of the same AI agent (Claude Sonnet 4.6) implementing "add a global feed" on each platform, with and without Vise. Without Vise: every run ships a hardcoded API key (a deterministic failure that cannot be attested). With Vise: every run passes CI with zero deterministic failures.
+
+For full methodology, per-cell scorecards, and the v0.7 multi-outcome cross-tool validation (chat / comments / push on React + Flutter, plus Antigravity/Gemini cross-tool), see [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) in the installed npm package.
+
+---
+
+## Changelog
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for the full version history.
+
+---
+
+## Support
+
+- **Bugs / feature requests:** contact your social.plus account team or file an issue with your integration partner.
+- **Documentation:** [https://learn.social.plus](https://learn.social.plus)
+- **Skill installation issues:** `vise doctor` prints diagnostic info; share the output with support.
+
+---
+
+## License
+
+Proprietary. See [`LICENSE`](./LICENSE) for terms. social.plus Vise is provided to social.plus customers and integration partners under the same agreement as the social.plus SDK.
+
+---
+
+<p align="center">
+  Built with <code>vise</code>. Holding compliance steady so agents can build.
+</p>