2 Commits

Include renames

Author	SHA1	Message	Date
4 people	6605b7b14a	feat+docs+release(v0.4.3): D76 — README install-path overhaul + OLP_BIND env + AI-install prompt + ADR 0011 amendment (#48) ... 10 README install gaps catalogued and fixed in one D-day after v0.4.2's PI231 E2E session exposed that the v0.4.0-v0.4.2 README Quick Start was fictional (npm package isn't published; olp setup/start commands don't exist). F5 (OLP_BIND env) ships in the same patch so the documented LAN onboarding flow actually works. AI-driven install prompt added per Phase 4 charter brainstorm Top-5 inheritance candidate #2 (D64-D67 built the doctor framework; D76 closes the README half). ## G1-G7: README Quick Start now real Rewrote § "Manual install" from placeholder text to the empirically-verified sequence: - Prerequisites (Node >= 18 + provider CLI install matrix) - git clone + npm test verify - olp-keys keygen --owner FIRST (allow_anonymous=false default needs a key) - Per-provider OAuth (claude setup-token / codex login --device-auth / MISTRAL_API_KEY) - ~/.olp/config.json with the minimum that actually serves traffic - npm start - Smoke-test via curl + olp doctor - IDE pointing ## G8 / F5: OLP_BIND env shipped server.mjs: - const BIND = process.env.OLP_BIND ?? '127.0.0.1' (safe default unchanged) - server.listen(PORT, BIND, ...) replaces hard-coded '127.0.0.1' - New startup warn anonymous_key_advertised_with_lan_bind fires when OLP_BIND is non-loopback AND auth.advertise_anonymous_key: true (operator visibility into trust-context overlap) Pre-D76 the server only accepted loopback connections, so the documented olp-connect <ip> family-onboarding flow was unreachable from LAN without SSH tunneling. F5 makes ADR 0011 operational instead of aspirational. ## G10: AI-driven install prompt README § "Install with your AI (the fast path)" — verbatim prompt the operator pastes into Claude Code / Cursor / Copilot / Aider. The AI follows README + uses olp doctor --json next_action.ai_executable[] for self-repair, stopping only when human_required[] is non-empty (provider OAuth dances). Closes the Phase 4 brainstorm #2 inheritance candidate. ## Opening compressed § "Why OLP" (3 paragraphs of Anthropic 2026-06-15 billing history) removed from the top. The OCP-trigger context moved to § "Migration from OCP" at the bottom, condensed into a single paragraph. New users land on value-prop + § "What you get" + install paths without needing to digest 2026-05-14 billing history first. OCP users get a one-line pointer at the top. ## Configuration + Env Variables sections updated - § Configuration: placeholder replaced with full ~/.olp/config.json schema documentation, every field cross-referenced to its ADR - § Environment Variables: added OLP_BIND, OLP_API_KEY, OLP_OWNER_TOKEN, OLP_PROXY_URL rows that were used in the manual-install flow but previously undocumented ## ADR 0011 § Deployment configurations amendment Codifies the three deployment trust contexts: - 127.0.0.1 (loopback only) — safe with any auth posture - RFC1918 / tailnet / specific LAN IP — anonymous_key OK (the documented trusted-LAN zero-config family onboarding flow) - Public IP — incompatible with advertise_anonymous_key: true Documents the new anonymous_key_advertised_with_lan_bind startup warn event. Closes ADR 0011's pre-D76 dangling reference to a non-existent BIND_ADDRESS concept. ## Test count 714 (v0.4.2) -> 717 (v0.4.3). +3 D76 regression tests in Suite 36 (36s/36t/36u) pinning OLP_BIND wiring + safety warn + ADR amendment. ## Process learning Every D-day reviewer rubric should add "open README §-Quick-Start and verify the commands literally exist + work in the current repo" — would have caught G1-G7 at v0.4.0 close. Combined with D74 (review-against-spec) + D75 (review-without-deployment), D76 (review-without-following-README) codifies the third tier of review discipline. ## Out of D76 scope (deferred) - F6 (doctor client-side vs server-side check separation) — needs design ADR for --remote mode. Phase 5. - D75 reviewer P2-1 (ADR 0004 per-hop schema amendment) + P2-2 (defensive typeof hopModel === 'string') — both genuine follow-ups, neither blocking. - scripts/migrate-from-ocp.mjs — Phase 7. Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-26 13:32:02 +10:00
4 people	0bdecd1235	feat+test+docs: D68-D70 — bin/olp-connect + /health.anonymousKey + ADR 0011 (#43) ... * feat+test+docs: D68+D69+D70 — bin/olp-connect + /health.anonymousKey + ADR 0011 Third substantive Phase 4 implementation. 3 D-days bundled per Iron Rule 11 IDR — olp-connect consumes /health.anonymousKey for zero-config client setup, both governed by ADR 0011's trusted-LAN-only invariant. ## D68 — bin/olp-connect (zero-config client setup) Ports OCP ocp-connect (721 lines) → OLP olp-connect (564 lines, pure bash). Bash over Node (per ADR 0010 § Notes) because client machines may lack recent Node; bash + curl + python3 = max portability. CLI: `olp-connect <host-ip> [--port PORT] [--key API_KEY] [--no-system-env] [--dry-run] [--help] [--version]` Workflow: 1. Connectivity probe (curl /health, 5s timeout, distinguishes TCP unreachable from auth-required) 2. Auth resolution: --key flag → /health.anonymousKey (D69) → interactive prompt fallback 3. Smoke test (GET /v1/models with bearer) 4. IDE detection + per-IDE config: - Claude Code: detect + warn (NOT supported as OLP client per ADR 0010) - Cline: detect + print manual VSCode-settings snippet - Continue.dev: detect (extension OR ~/.continue/config.yaml) + write idempotent models: entry - Cursor: detect + print snippet + WARNING (per prior-art known base-URL fragility) - Aider: detect + write OPENAI_API_BASE + OPENAI_API_KEY to rc files - OpenClaw: detect + print "install /olp plugin (D71-D73 deliverable)" 5. System-level env: macOS launchctl setenv / Linux ~/.config/environment.d (so VSCode/Cursor started via Dock inherit) 6. Summary + test command Idempotent (bracketed `# OLP LAN (added by olp-connect)` ... `# /OLP LAN` blocks in rc files). --dry-run exercises every state-change site without modifying anything. Exit 0/1/2 conventions. Installed via package.json bin so `npx olp-connect` works. ## D69 — /health.anonymousKey + auth.advertise_anonymous_key server.mjs handleHealth emits OPTIONAL `anonymousKey: "olp_..."` field when ALL THREE prerequisites hold: 1. config.json auth.advertise_anonymous_key === true 2. config.json auth.allow_anonymous === true (per ADR 0007 § 7) 3. At least one non-revoked key has plaintext_advertise field set Default-off: field is ABSENT (not null) — preserves v0.3.x /health shape; existing tests don't regress. bin/olp-keys.mjs new flags: `keygen --anonymous --advertise` writes the plaintext into the manifest's optional `plaintext_advertise` field AND prints a WARNING about disk-storage + /health exposure + ADR 0011 pointer. Owner-tier --advertise rejected at BOTH CLI + lib layers. Implementation note: reused existing guest tier (no new owner_tier: 'anonymous'); plaintext_advertise is a forward-compat optional manifest field per ADR 0007 § 4 unknown-fields-allowed convention. Cleaner than introducing a new tier. anonymousKey appears in BOTH trimmed AND full /health payloads — the trimmed payload's purpose is to be readable by anonymous clients so they can self-bootstrap. Tested. Startup warns on prereq failure (anonymous_key_advertised_but_denied / anonymous_key_advertised_but_no_anonymous_key_exists) so the relaxed- posture failure mode is observable. Graceful-degrade: server still boots; handleHealth re-checks at request time and silently omits the field when any prereq fails (defense-in-depth). ## D70 — ADR 0011 (anonymous-key deployment-context limits) New ADR codifying the trusted-LAN-only invariant. Trade-off documented: anonymous key advertised via /health = anyone who can reach the server can read /health and use the key. Acceptable ONLY when "anyone who can reach the server" ≈ "trusted family on the LAN". Public-internet deployment = instant compromise. Soft enforcement: server logs startup warn if BIND_ADDRESS resolves to a public IP AND advertise_anonymous_key: true. No hard allowlist (TLS- fronted private networks indistinguishable from public from server's perspective). Re-evaluation trigger: any time OLP gains "expose to public internet" deployment mode (e.g., Cloudflare Tunnel guidance in README), revisit. References ADR 0007 § 7 (identity classes), ADR 0010 § Phase 4 charter D68-D70 line, OCP server.mjs:148/1454/1488/1555 (PROXY_ANONYMOUS_KEY reference). ## Test count 658 → 672 (+14 D68-D70 tests across Suite 34: 5 keys.mjs unit + 6 /health HTTP integration + 3 CLI integration). ## Scope discipline NO /v1/messages entry surface (out of Phase 4 per ADR 0010). NO olp-plugin/ Telegram plugin (D71-D73). NO docs/integrations/*.md files (D71-D73). NO CHANGELOG / package.json version bump (Phase 4 close handles versioning; only package.json bin entry for olp-connect added). NO new npm deps. ## Authority - ADR 0010 § Phase 4 D-day plan D68-D70 line - ADR 0011 (this commit — new ADR) - ADR 0007 § 4 (manifest forward-compat unknown fields) + § 7 (identity classes) + § 9 (keygen flow) — extended by D69 plaintext_advertise - OCP ocp-connect /Users/taodeng/ocp/ocp-connect (port reference) - OCP server.mjs:148, 1454, 1488, 1555 (PROXY_ANONYMOUS_KEY reference) - 2026-05-26 brainstorm (Top 5 OCP inheritance candidates, item 3: /health.anonymousKey + olp-connect zero-config UX) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix: D68-D70 reviewer P1 + P2 fold-in — README impact note + listKeys redaction + schema_version note Reviewer APPROVE WITH MINOR — 0 P0, 1 P1, 2 P2; all three folded in. P1 — README impact note for new Phase 4 user-visible surfaces. Per CLAUDE.md release_kit.new_feature_doc_expectations: - new env / config knob → README § Environment Variables - new endpoint or response field → README § API Endpoints - new CLI surface → dedicated § README now documents: - /health.anonymousKey optional field (in API Endpoints table) with cross- ref to ADR 0011 + the three-prereq gate - streaming.heartbeat_interval_ms config (D61) + auth.advertise_anonymous_key config (D69) under new "config.json keys introduced at Phase 4" subsection - Operator CLI surfaces summary: olp / olp-connect / olp-keys keygen --anonymous --advertise, with cross-refs to ADR 0010 + 0002 Amendment 7 P2-1 — lib/keys.mjs listKeys() now strips plaintext_advertise alongside token_hash. Callers wanting the advertised plaintext for the /health publication path MUST go through findAdvertisedKey() — the only sanctioned read site. Defends against a future caller of listKeys() leaking the plaintext into logs / HTTP responses / dashboards. Tests still pass (no in-repo caller of listKeys depends on plaintext_advertise being present). P2-2 — ADR 0011 now documents the schema_version-stays-at-1 decision explicitly. Additive optional fields don't require bump per ADR 0007 § 4, but a future archaeologist asking "why didn't D69 bump schema_version?" now has a one-line answer. Same paragraph documents the listKeys() redaction policy in plain text alongside the manifest-field contract. 672/672 tests still pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-26 09:15:09 +10:00