@amityco/social-plus-vise 0.4.0

package/rules/security.yaml

@@ -0,0 +1,162 @@
+{
+  "domain": "security",
+  "schema_version": 1,
+  "rules": [
+    {
+      "id": "typescript.secret.inline-api-key",
+      "version": 1,
+      "title": "TypeScript API keys must not be hardcoded in source",
+      "severity": "warning",
+      "rationale": "Inline API keys are committed to version control. Use the host app's environment or config pattern instead.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.secret.inline-api-key" }],
+        "attestation": { "allowed": false, "host_agent_min_confidence": "high", "human_allowed": false, "evidence_required": [] }
+      }
+    },
+    {
+      "id": "react-native.secret.inline-api-key",
+      "version": 1,
+      "title": "React Native API keys must not be hardcoded in source",
+      "severity": "warning",
+      "rationale": "Inline API keys are committed to version control. Use the host app's environment or config pattern instead.",
+      "applies_when": { "platforms": ["react-native"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "react-native.secret.inline-api-key" }],
+        "attestation": { "allowed": false, "host_agent_min_confidence": "high", "human_allowed": false, "evidence_required": [] }
+      }
+    },
+    {
+      "id": "typescript.secret.committed-env",
+      "version": 1,
+      "title": "TypeScript local env files must not contain committed API keys",
+      "severity": "warning",
+      "rationale": "A committed .env file can leak customer social.plus API keys. Commit templates, not live values.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.secret.committed-env" }],
+        "attestation": { "allowed": false, "host_agent_min_confidence": "high", "human_allowed": false, "evidence_required": [] }
+      }
+    },
+    {
+      "id": "typescript.secret.env-gitignore",
+      "version": 1,
+      "title": "TypeScript env secret files should be ignored",
+      "severity": "warning",
+      "rationale": "When SDK secrets are loaded from env files, local env files should be ignored so customer API keys are not accidentally committed.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.secret.env-gitignore" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "gitignore_policy", "description": "Where local env files are ignored or otherwise prevented from commit.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "typescript.secret.env-example",
+      "version": 1,
+      "title": "TypeScript env secret config should have an example file",
+      "severity": "warning",
+      "rationale": "A placeholder env example lets agents and developers create local config without asking users to paste secrets into chat.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.secret.env-example" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "template_path", "description": "Path to the committed env/config template with placeholder secret keys.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "android.secret.inline-api-key",
+      "version": 1,
+      "title": "Android API keys must not be hardcoded in source",
+      "severity": "warning",
+      "rationale": "Inline API keys are committed to version control. Use BuildConfig, gradle properties, or a runtime secrets store instead.",
+      "applies_when": { "platforms": ["android"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "android.secret.inline-api-key" }],
+        "attestation": { "allowed": false, "host_agent_min_confidence": "high", "human_allowed": false, "evidence_required": [] }
+      }
+    },
+    {
+      "id": "flutter.secret.inline-api-key",
+      "version": 1,
+      "title": "Flutter API keys must not be hardcoded in source",
+      "severity": "warning",
+      "rationale": "Inline API keys are committed to version control. Use --dart-define, dotenv, or a runtime secrets store instead.",
+      "applies_when": { "platforms": ["flutter"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "flutter.secret.inline-api-key" }],
+        "attestation": { "allowed": false, "host_agent_min_confidence": "high", "human_allowed": false, "evidence_required": [] }
+      }
+    },
+    {
+      "id": "ios.secret.inline-api-key",
+      "version": 1,
+      "title": "iOS API keys must not be hardcoded in source",
+      "severity": "warning",
+      "rationale": "Inline API keys are committed to version control. Use xcconfig, Info.plist references, or a runtime secrets store instead.",
+      "applies_when": { "platforms": ["ios"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "ios.secret.inline-api-key" }],
+        "attestation": { "allowed": false, "host_agent_min_confidence": "high", "human_allowed": false, "evidence_required": [] }
+      }
+    },
+    {
+      "id": "android.logging.no-secret-in-log",
+      "version": 1,
+      "title": "Android logging must not include secret-shaped values",
+      "severity": "warning",
+      "rationale": "Logging apiKey, accessToken, refresh token, password, or other secret-shaped values to Log.* or println escapes secrets to crash reports, log aggregators, and shoulder surfers. Drop the log line or redact the value.",
+      "applies_when": { "platforms": ["android"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "android.logging.no-secret-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Where the value being logged is redacted or proven to be a placeholder.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "flutter.logging.no-secret-in-log",
+      "version": 1,
+      "title": "Flutter logging must not include secret-shaped values",
+      "severity": "warning",
+      "rationale": "Logging apiKey, accessToken, refresh token, password, or other secret-shaped values to print, debugPrint, or developer.log escapes secrets to crash reports and log aggregators. Drop the log line or redact the value.",
+      "applies_when": { "platforms": ["flutter"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "flutter.logging.no-secret-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Where the value being logged is redacted or proven to be a placeholder.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "ios.logging.no-secret-in-log",
+      "version": 1,
+      "title": "iOS logging must not include secret-shaped values",
+      "severity": "warning",
+      "rationale": "Logging apiKey, accessToken, refresh token, password, or other secret-shaped values via print, NSLog, os_log, or Logger escapes secrets to the system log and crash reports. Drop the log line or redact the value.",
+      "applies_when": { "platforms": ["ios"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "ios.logging.no-secret-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Where the value being logged is redacted or proven to be a placeholder.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "typescript.logging.no-secret-in-log",
+      "version": 1,
+      "title": "TypeScript logging must not include secret-shaped values",
+      "severity": "warning",
+      "rationale": "Logging apiKey, accessToken, refresh token, password, or other secret-shaped values via console.* escapes secrets to browser devtools, server logs, and error trackers. Drop the log line or redact the value.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.logging.no-secret-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Where the value being logged is redacted or proven to be a placeholder.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "react-native.logging.no-secret-in-log",
+      "version": 1,
+      "title": "React Native logging must not include secret-shaped values",
+      "severity": "warning",
+      "rationale": "Logging apiKey, accessToken, refresh token, password, or other secret-shaped values via console.* escapes secrets to Metro, Flipper, and crash reports. Drop the log line or redact the value.",
+      "applies_when": { "platforms": ["react-native"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "react-native.logging.no-secret-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Where the value being logged is redacted or proven to be a placeholder.", "upload_policy": "upload-with-consent" }] }
+      }
+    }
+  ]
+}

package/skills/social-plus-vise/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: social-plus-vise
+description: Use when implementing, validating, or debugging social.plus SDK features in a customer project. Guides the host AI agent to use the Vise CLI for docs lookup, project inspection, implementation planning, validation, and sensor runs instead of guessing SDK APIs or integration details.
+---
+
+# social.plus Vise
+
+Vise is the deterministic tool surface. This skill is the AI-agent workflow layer.
+
+Use the CLI first. Use MCP only when the host already has Vise MCP tools connected.
+
+## Required Loop
+
+Before editing customer code:
+
+```bash
+vise inspect .
+vise plan . --request "<user intent>"
+vise init . --request "<user intent>"
+```
+
+Then fetch docs cited by the plan or relevant to the requested feature:
+
+```bash
+vise search-docs "<SDK feature or API pattern>"
+vise get-doc-page "<canonical-doc-path>"
+```
+
+After editing:
+
+```bash
+vise check .
+vise sync .
+vise validate .
+vise run-sensors .
+```
+
+Treat Vise runtime smoke sensors as real validation. For TypeScript/React Native projects, `vise run-sensors` may include `TypeScript SDK import smoke`; if it fails, the SDK package does not resolve from the host project runtime and the integration is not done.
+
+In CI or pull-request pipelines, use `vise check . --ci`. It is read-only, exits non-zero unless compliance is green, and never writes deterministic-pass records; use `vise sync` only during the implementation loop after a local green check.
+
+## Engagement Scope (Optional)
+
+If the customer has set up `sp-vise/engagement.json` (via `vise engagement init`), respect the declared scope. `vise engagement show .` prints the engagement metadata: tier, customer id, contracted outcomes, reviewer assignment.
+
+When `vise init` reports a `warnings` array containing "not in the engagement scope", surface that to the user — don't silently widen scope. The user either extends the scope by editing `engagement.json` or accepts that the current work is out-of-contract.
+
+If no `engagement.json` exists, do not create one without the user's intent. `vise engagement init` is a contractual artifact; agents should only run it when the user explicitly asks to set up engagement metadata, typically with `--tier`, `--customer-id`, and `--scope`.
+
+If `vise` is not installed, use:
+
+```bash
+npm install -g @amityco/social-plus-foundry
+```
+
+Then retry the `vise` command.
+
+## Stop Instead Of Guessing
+
+Ask the user before editing when required values are missing:
+
+- region, auth/user identity, or session-handler ownership (which class/module implements `sessionWillRenewAccessToken`)
+- feed target, community ID, target ID, feed ID, or channel ID
+- notification platform type, token source, permission owner, or logout cleanup owner
+- Live Object/Collection domain, object vs collection choice, lifecycle owner, or cleanup location
+- app surface in a monorepo when Vise reports multiple surfaces
+- design-token, theme, or component source for UI work
+
+Never invent undocumented SDK APIs, IDs, credentials, or design systems.
+
+## Secret Handling
+
+Never ask the user to paste API keys, Firebase/APNS credentials, server-issued tokens, or other secrets into chat.
+
+When a secret is required:
+
+1. Find the app's existing environment/config pattern.
+2. Create or update a non-secret template such as `.env.example`, and ensure local env files are ignored by git before telling the user where to put real values.
+3. Add placeholder names only, such as `VITE_AMITY_API_KEY=`.
+4. Tell the user exactly which local file and variable to fill in themselves.
+5. Do not echo, log, commit, or attest the secret value.
+
+If no safe ignored local env path or template path is clear, stop and tell the user which variable names are needed.
+
+Do not write a real `.env` value for the user. If you create a local env file during implementation, it must contain placeholders only and the project must already ignore it. `vise check` flags committed env secrets and missing TypeScript env hygiene.
+
+## Logging Discipline
+
+Do not pass secret-shaped values (`apiKey`, `apiSecret`, `accessToken`, `refreshToken`, `bearerToken`, `clientSecret`, `password`) to logging calls. This includes:
+
+- TypeScript / React Native: `console.log/info/warn/error/debug`
+- Android Kotlin / Java: `Log.d/i/e/v/w`, `println`, `print`
+- Flutter Dart: `print`, `debugPrint`, `developer.log`
+- iOS Swift: `print`, `NSLog`, `os_log`, `Logger.log/info/debug/...`
+
+`vise check` enforces `*.logging.no-secret-in-log` per platform. If you need to log around a value for debugging, log a redacted form (`apiKey ? "<set>" : "<missing>"`), not the value itself. Remove debug log lines before declaring done.
+
+## Session Renewal
+
+When you call SDK `login`, also implement the session-renewal handler in the same change. Access tokens expire in production; without a renewal handler the SDK cannot refresh and customers see silent auth failures.
+
+Per platform:
+
+- TypeScript / React Native: pass `sessionHandler` to `Client.login`, implement `sessionWillRenewAccessToken(renewal)` and call `renewal.renew()`.
+- Android Kotlin: pass `AmitySessionHandler` to `AmityCoreClient.login`, override `sessionWillRenewAccessToken` and call `renewal.renew()`.
+- Flutter Dart: implement `AmitySessionHandler.sessionWillRenewAccessToken(AmityAccessTokenRenewal)` and call `renewal.renew()`.
+- iOS Swift: implement `AmitySessionHandler.sessionWillRenewAccessToken(renewal:)` and call `renewal.renew()`.
+
+`vise check` enforces `*.session.renewal` per platform when login is present.
+
+## SDK Version Handling
+
+Do not use floating SDK dependency versions such as `latest`, `*`, `any`, `+`, or branch-based iOS package references. Pin the social.plus SDK to an explicit version or reviewed semver range, then let the host app's package manager lockfile capture the exact resolved version.
+
+## Attestation Flow
+
+`vise check` reports each applicable rule as one of `deterministic-pass`, `attestation-needed`, `failed`, or `blocked`. `attestation-needed` and `failed` are NOT warnings to skip — they block "I'm done." Resolve them in one of two ways:
+
+1. **Make the deterministic check fire (preferred).** Re-read `vise explain <rule-id>` for the rule's enforcement details, adjust the code so the check passes, then run `vise check` again. After it goes green, run `vise sync` to persist the deterministic-pass attestation files.
+2. **Record an attestation with evidence.** When the rule cannot fire because the customer's architecture is unconventional (DI wrappers, custom abstractions, etc.), use `vise attest`:
+
+```bash
+vise attest . \
+  --rule typescript.client.region \
+  --confidence high \
+  --signer host-agent \
+  --rationale "API_REGIONS.EU is explicitly passed as the second argument to Client.createClient in src/socialSDK.ts." \
+  --evidence-file ./.tmp/evidence.json
+```
+
+The evidence file is a JSON object matching the `evidence_required` schema for that rule (`vise explain <rule-id>` shows the required fields). Include concrete source file paths in evidence values whenever the evidence depends on code, for example `{ "region_source": "src/socialSDK.ts" }` or `{ "login_flow": "src/auth/socialSession.ts" }`. `vise attest` fingerprints cited files, and future `vise check` runs mark the attestation stale if those files change.
+
+### Confidence honesty
+
+- `high` — direct evidence the deterministic check would have fired if it had been more flexible. Auto-recorded.
+- `medium` — reasoned about it but cannot point to a single unambiguous location. May require human signer depending on rule.
+- `low` — guess. Always requires `--signer human`.
+
+If the rule's `escalation_threshold` is above your confidence, `vise attest --signer host-agent` is rejected. In v0.4 there is no hosted review queue yet, so the path is: stop, surface to the user with the rule id and the evidence you have, and ask them to run `vise attest --signer human --identity <their name or email>` themselves.
+
+### What `vise sync` is NOT
+
+- `vise sync` does **not** accept `--attest` or any flag. It only persists deterministic-pass results.
+- Passing unknown flags to `vise sync` will error in v0.4 — don't try to use it as a shortcut for attestation.
+- To record an attestation, use `vise attest`. Always.
+
+### Treat warnings as blockers
+
+If a legacy `vise validate` run reports `needs-review` with warnings, those warnings correspond to compliance rules in `attestation-needed` state. Do not interpret them as "code is fine, just static-analysis noise." Run `vise check` to get the structured rule list, then resolve each one as above.
+
+## Feature Guidance
+
+For feed or post creation:
+
+```bash
+vise search-docs "create post feed target"
+vise plan . --request "<feed or post request>"
+```
+
+Require a concrete target from the app: current user feed, selected community, selected channel, or another user-provided domain object. Do not hardcode random target IDs.
+
+For notification setup:
+
+```bash
+vise search-docs "push notification device token unregister"
+vise plan . --request "<notification request>"
+```
+
+Require platform, credential assumptions, device-token ownership, permission flow, registration timing after login, and unregister cleanup on logout or user switch.
+
+For Live Objects or Live Collections:
+
+```bash
+vise search-docs "Live Collection observe cleanup"
+vise plan . --request "<live data request>"
+```
+
+Require object vs collection, observed domain, lifecycle owner, loading/error/update states, and observer/subscription cleanup.
+
+## Monorepos
+
+If `vise inspect .` reports multiple surfaces, choose the intended app with the user or surrounding task context. Pass it consistently:
+
+```bash
+vise plan . --surface apps/web --request "<user intent>"
+vise validate . --surface apps/web
+vise run-sensors . --surface apps/web
+```
+
+## Final Response Discipline
+
+Report:
+
+- Vise commands used
+- docs pages used
+- files changed
+- validation findings
+- sensor results or why sensors were skipped
+- unresolved user inputs or stop conditions