chrisfu/prole
1
0
Fork 0
mirror of https://github.com/dredx/prole.git synced 2026-09-23 12:03:59 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
00f0ebec07
prole/docs/plans
History
chrisfu 00f0ebec07 Merge claude/crazy-bose-fec256 into main 
Bringing the long-running session-feature branch back into main in one
deliberate sweep. The branch carried the cluster work that's been live for
weeks (cross-cluster CNPG metrics, Grafana w/ Google OAuth, supabase
oauth2-proxy, cluster recovery, pg.0.knoe.dev + per-engineer onboarding,
GCS-backed CNPG backups via Workload Identity, the env-contamination
guard, the Junie brief queue, the cnpg-grafana CSRF + memory-request
fixes from today), while main accumulated Junie's parallel knoe-auth
Phase 2 OIDC work (full provider surface: discovery, authorize, token,
userinfo, JWKS, RS256 signing, code exchange, session services).

Key decision: the two branches did COMPETING rebrands off the same
starting point (5ba9b63, 2026-04-27):

  - claude branch (commit b355855, earlier): org.prole.authority.* →
                                              dev.knoe.auth.*
                                              (artifact renamed to
                                              knoe-auth.jar)
  - main (commit 9daa94b, recent): org.prole.authority.* →
                                    dev.knoe.authority.*
                                    (kept "authority" artifact name)

dev.knoe.auth wins: cluster runs from this name, the Maven artifact is
already knoe-auth.jar, and the broader rename is the documented
namespace direction (per ~/.claude/projects/-Users-chrisfu-dev-knoe-db/
memory/MEMORY.md). All of main's recent Phase 2 OIDC content was ported
from authority/src/.../dev/knoe/authority/ into
authority/src/.../dev/knoe/auth/ with package declarations rewritten.

== File-level resolution summary ==

Textual conflicts (4):

  authority/pom.xml
    - Took our artifactId="auth"
    - Took our branch's removal of spring-security-kerberos-client
      (verified: Junie's Phase 2 OIDC code does not import it; the dep
      was already-dead config)

  docs/pipeline-phases.md
    - Took our branch's "Phase 1 not started" status. Main had a
      misplaced "✅ Complete" with a knoe-auth-Phase-1 commit ref
      in the autobuild Phase 1 section — different domain.

  docs/plans/knoe-auth-round-1.md
    - Took our branch's dev.knoe.auth file table (vs main's
      dev.knoe.authority listing). Pure rename mismatch.

  supabase/helm/knoe-supabase/templates/kong/config.yaml
    - Took our branch's onboard route + plain dashboard wiring.
      Main had an oauth2proxy.enabled toggle that put oauth2-proxy as
      a Kong upstream — but the deployed architecture (commit 25f1b2e)
      has oauth2-proxy in FRONT of Kong, not behind. Main's wrapper
      reflected an architecture that was never deployed.
    - Took our branch's removal of basic-auth from dashboard route
      (queue #15 brief still tracks the matching values.yaml /
      kong/deployment.yaml cleanup).

Java tree reconciliation (44 file-pairs):

  20 dual-path source files + 2 dual-path tests
    Body-identical between main's authority/ and our branch's auth/
    after stripping package decls — main's commit 9daa94b was a pure
    rebrand. Took our branch's auth/ version for all 22.

  8 main-only source files (Phase 2 OIDC), ported into auth/:
    web/JwksController.java
    web/OidcAuthorizeController.java
    web/OidcDiscoveryController.java
    web/OidcTokenController.java
    web/OidcUserInfoController.java
    session/OidcCodeService.java
    session/OidcTokenService.java
    session/SessionService.java

  12 main-only test files, ported into auth/:
    HealthControllerTest.java
    enroll/EnrollValueTypesTest.java
    enroll/EnrollmentControllerTest.java
    enroll/TotpServiceTest.java
    kerberos/KadminClientTest.java
    kerberos/KerberosSpnegoResultTest.java
    web/LoginControllerTest.java
    admin/AdminControllerTest.java
    user/PrincipalNormalizerTest.java
    regression/IdentityRegressionTest.java
    session/OidcCodeServiceTest.java
    session/SessionServiceTest.java

  Port mechanics: read main:authority/...<file> via git show, then sed
  rewrite `package dev.knoe.authority` → `package dev.knoe.auth` and
  `import dev.knoe.authority` → `import dev.knoe.auth`. Body content
  unchanged.

  authority/src/main/java/dev/knoe/authority/ — DELETED (duplicate)
  authority/src/test/java/dev/knoe/authority/  — DELETED (duplicate)

== Verification ==

- grep -rln '<<<<<<<' across .java/.md/.yaml/.yml/.sh/.xml/.tpl: clean
- find authority/src -path '*/dev/knoe/authority*': empty (subtree gone)
- grep 'package dev.knoe.authority' across repo: clean
- bash -n install.sh deploy.sh etc/preflight_kubecontext.sh: clean
- git ls-files -u | wc -l: 0 unmerged paths
- helm lint supabase/helm/knoe-supabase: pre-existing failure on
  studioIngress.enabled undefined in values.yaml (introduced by Junie
  on main; unrelated to this merge — flagging as follow-up).

== Followups (carried into TODO ranked queue or noted here) ==

  - helm lint failure: studioIngress block in values.yaml is missing
    enable flag; templates/studio/{ingress,oauth2proxy-deployment,
    oauth2proxy-service}.yaml all reference studioIngress.enabled with
    no default. Pre-existing on main; not introduced by this merge.
  - The five Junie briefs filed on this branch are now reachable from
    main at docs/plans/junie/{02,06,07,13,15}-*.md. Junie can pick them
    up in any order.
  - knoe-auth Phase 2 OIDC source (now at dev.knoe.auth.*) is not yet
    deployed to the cluster. Deployment is its own task.
  - The branch claude/crazy-bose-fec256 stays in place (worktree at
    .claude/worktrees/crazy-bose-fec256 may have ongoing context for
    Claude Code sessions). Safe to delete once next session starts
    cleanly from main.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-01 16:39:10 -07:00
..
junie docs(plans): file Junie briefs for queue items #2, #6, #7, #13, #15 2026-05-01 16:13:20 -07:00
customer-deploy-resync.md Merge claude/crazy-bose-fec256 into main 2026-05-01 16:39:10 -07:00
deployment-modes.md Merge claude/crazy-bose-fec256 into main 2026-05-01 16:39:10 -07:00
knoe-auth-round-1.md Merge claude/crazy-bose-fec256 into main 2026-05-01 16:39:10 -07:00
onboarding-tdd-phase-a.md Merge claude/crazy-bose-fec256 into main 2026-05-01 16:39:10 -07:00
onboarding-tdd.md test(infra): Phase A — onboarding TDD design doc + hard fixture 2026-04-30 16:07:39 -07:00
README.md Merge claude/crazy-bose-fec256 into main 2026-05-01 16:39:10 -07:00

README.md

Plans

Engineering plans for the knoe.dev platform. Each document scopes one initiative — its strategic context, design, schema, and the components it adds — and is intended to outlive the implementation work itself: when the work ships, the plan stays as the architectural reference.

Who this is for

You are a junior or mid-level engineer who has been invited to contribute to knoe.dev. These documents are written for you. They assume:

  • You are comfortable reading code and skimming a Maven pom.xml.
  • You have used Kubernetes at least casually (kubectl get pods, helm charts).
  • You may not have prior Kerberos, OIDC, or CNPG experience — relevant terms are defined inline or in the glossary section of each plan.
  • You have not seen this repo before. Each plan starts with the strategic context and links to existing code before it asks you to write any.

If a sentence in a plan assumes knowledge you don't have, that's a bug in the plan — open an issue.

What lives here

File Initiative When you should read it
knoe-auth-round-1.md Identity backbone for the platform: MIT Kerberos KDC + invite-anchored web enrollment + TOTP 2FA. Round 1 of N. Shipped. Before touching authority/, etc/init_kdc.sh, etc/init_knoe_users.sh, anything in deploy/gcp/gke/knoe-auth-* or knoe-kdc-*, or the knoe.* database schema.
deployment-modes.md Four-mode installer (min / k3d / k3s / gke) with a welcome-screen mode selector and a min-mode fast-path through the wizard. Shipped in Phase 0. Before touching knoe/ui/screens/welcome.py, knoe/ui/screens/navigation.py, or adding any new wizard screen.
customer-deploy-resync.md Original plan to converge ~/dev/prole onto knoe-db/main as a customer-deploy branch. Dormant — prole rebrand merged into main; no separate prole working tree currently under development. Only if you're considering activating a per-customer branching workflow.
junie/ (subdirectory) Self-contained, single-task work briefs for Junie to consume from inside the IDE. Tactical, single-MR scope, paired against numbered items in ../TODO.md. When you want to hand a discrete task to Junie or audit what's been queued.
../TODO.md (sibling) Master TODO index — single source of truth for unfinished work, including reality-vs-intent gaps flagged in CLAUDE.md/AGENTS.md. Before picking up any task, to see what's already on the queue.

Each plan follows the same shape: Context → How it's wired (file references) → Architecture → Schema / API → Step-by-step → Verification → Glossary.

Status conventions

A plan in this directory has one of three statuses, declared at the top:

  • Active plan. Not yet implemented. — the design is agreed, the code isn't there yet. Read deliverables top-to-bottom.
  • Implemented and operational. Architectural reference. — the work shipped. The doc explains how it works and why; cross-references point at real files. Read the context and the rationale; jump to specific sections when you have a question.
  • Archived. — superseded by a later round or a different approach. Lives in archive/ with a one-line "see X instead" pointer.

Customer deploys

The knoe.dev platform is designed to support per-customer deployments via branches in this repo, not separate forks. Customer-specific divergence (config, branding, on-prem manifests, kubeconfig handling) would live on a branch named after the customer; platform changes always land on main and customer branches rebase or merge from main on a regular cadence.

Currently no customer branch is active. The original plan to converge ~/dev/prole into a customer/prole.org branch is captured in customer-deploy-resync.md and is dormant — the prole→knoe rebrand has merged into main itself, and there is no separate ~/dev/prole working tree under development. origin and knoe remotes both point at upstream git@git-ssh.knoe.dev:knoe.dev/knoe-db.git.

How to propose a new plan

  1. Copy knoe-auth-round-1.md as a template — the section structure is the convention.
  2. Lead with why (one or two paragraphs). Half the value of a plan is forcing the author to articulate the motivation.
  3. Cite real files with paths relative to the repo root. If you reference something that doesn't exist yet, label it (net-new) so a reader doesn't go hunting.
  4. End with a Verification section — a short checklist a reviewer can run to decide whether the plan is done, or — once shipped — that the implementation still matches the spec.
  5. Open an MR. Plans are reviewed like code.