If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cookieY/Yearning shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 7mo ago

• Last commit 7mo ago
• 6 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Concentrated ownership — top contributor handles 67% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cookieY/Yearning repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cookieY/Yearning.

What it runs against: a local clone of cookieY/Yearning — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cookieY/Yearning | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch next exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 236 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cookieY/Yearning. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cookieY/Yearning.git
#   cd Yearning
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cookieY/Yearning and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cookieY/Yearning(\\.git)?\\b" \\
  && ok "origin remote is cookieY/Yearning" \\
  || miss "origin remote is not cookieY/Yearning (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify next >/dev/null 2>&1 \\
  && ok "default branch next exists" \\
  || miss "default branch next no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "src/engine/engine.go" \\
  && ok "src/engine/engine.go" \\
  || miss "missing critical file: src/engine/engine.go"
test -f "src/handler/order/audit/audit.go" \\
  && ok "src/handler/order/audit/audit.go" \\
  || miss "missing critical file: src/handler/order/audit/audit.go"
test -f "src/handler/order/query/query.go" \\
  && ok "src/handler/order/query/query.go" \\
  || miss "missing critical file: src/handler/order/query/query.go"
test -f "migration/migrate.go" \\
  && ok "migration/migrate.go" \\
  || miss "missing critical file: migration/migrate.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 236 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~206d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cookieY/Yearning"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Yearning is a locally-deployed SQL audit and query control platform specifically built for MySQL, running as a Go binary with built-in AI-assisted SQL optimization. It provides SQL pre-execution approval workflows, automated syntax checking via configurable rules, query auditing with field anonymization, and DDL/DML rollback statement generation—solving the problem of unsafe SQL execution in production databases without cloud dependencies. Monolithic Go binary architecture: cmd/ contains CLI entry points (cmd/cli.go, cmd/cmd.go), src/apis/ provides REST endpoints (dash.go, query.go, fetch.go), src/handler/ manages business logic split by domain (dashboard.go, fetch/ai.go for AI features, common/ for shared utilities), src/engine/ wraps the SQL execution engine, and migration/ handles schema versioning. Configuration via conf.toml.template; Docker deployment included.

Database administrators (DBAs) and development teams managing MySQL instances who need to enforce SQL governance, audit user queries, and prevent dangerous statements from reaching production. Teams prioritizing privacy and on-premise deployments rather than SaaS solutions.

Actively maintained production-ready project with 235KB+ of Go code, GitHub Actions CI/CD pipelines (docker-build-push.yml, check-issue.yml), comprehensive test coverage (migration_test.go present), and multi-language documentation (README in English, Chinese, Japanese). The project shows regular releases and community engagement via GitHub Issues/PRs.

Moderate risk: single maintainer (cookieY), moderate dependency load (~25 direct dependencies including gorm, go-openai, ldap), last observable state shows active development but no timestamp provided for latest commit. Breaking changes are possible given the feature velocity (AI features, OIDC login additions). Database migrations must be tested carefully given the audit-critical nature.

Recent work includes AI assistant expansion (text-to-SQL conversion visible in src/handler/fetch/ai.go), OIDC authentication integration (img/oidclogin.gif), and GitHub Actions workflows for automated issue translation and Docker builds. Dependabot is configured for dependency updates.

git clone https://github.com/cookieY/Yearning.git && cd Yearning && go build -o Yearning main.go && ./Yearning install && ./Yearning run (requires MySQL configured in config.toml)

Daily commands: ./Yearning install (schema init) && ./Yearning run (starts server) — see cmd/cmd.go for full CLI interface; Docker: docker-compose up (docker/docker-compose.yml)

• main.go — Application entry point that initializes the SQL audit platform, loads configuration, and starts the server.
• src/engine/engine.go — Core SQL parsing and audit engine—all query validation and analysis logic depends on this.
• src/handler/order/audit/audit.go — Primary audit request handler orchestrating the SQL review workflow and approval chain.
• src/handler/order/query/query.go — Query execution handler that bridges audit approval to safe database statement execution.
• migration/migrate.go — Database schema initialization and migrations—breaking changes here affect all deployments.
• go.mod — Dependency manifest (GORM, jwt, OpenAI, LDAP)—critical for understanding framework constraints.
• conf.toml.template — Configuration template covering database, auth, AI integration, and LDAP settings.

Add a new SQL audit rule

1. Define the rule structure in src/handler/common/types.go (add a Rule model field or expression) (src/handler/common/types.go)
2. Implement rule evaluation logic in src/engine/engine.go (extend the audit analysis function) (src/engine/engine.go)
3. Create a handler in src/handler/manage/ to expose CRUD endpoints for the rule (src/handler/manage/board.go)
4. Add migration to create the rule table in migration/migrate.go (migration/migrate.go)

Add a new authentication provider (e.g., Google OAuth)

1. Create src/handler/login/googleLogin.go following the pattern of oidcLogin.go (src/handler/login/oidcLogin.go)
2. Add configuration fields to conf.toml.template for the new provider (conf.toml.template)
3. Register the new handler in main.go and add route in src/handler/login/login.go (src/handler/login/login.go)

Add a new API endpoint for audit data export

1. Add export handler function to src/handler/order/audit/audit.go (src/handler/order/audit/audit.go)
2. Implement export logic (CSV/Excel generation) in src/handler/order/audit/impl.go (src/handler/order/audit/impl.go)
3. Register route in src/handler/order/audit/route.go with authentication middleware (src/handler/order/audit/route.go)
4. Add error handling messages to src/i18n/cn.go and src/i18n/us.go (src/i18n/us.go)

Extend the approval workflow with conditional logic

1. Define new condition types in src/handler/common/types.go (add Workflow and ApprovalRule models) (src/handler/common/types.go)
2. Implement condition evaluation in src/handler/common/expr.go to evaluate approval rules (src/handler/common/expr.go)
3. Update src/handler/manage/flow/impl.go to apply conditions during audit review (src/handler/manage/flow/impl.go)

• Go + Yee framework — Lightweight HTTP routing with built-in middleware support; minimal runtime overhead for DBA-facing audit service.
• GORM + MySQL driver — ORM for schema management and query safety; native MySQL compatibility aligns with target database.
• JWT (golang-jwt) — Stateless session management suitable for distributed deployments; no shared session store required.
• LDAP + OIDC — Enterprise SSO integration for compliance and user management at scale without local password storage.
• OpenAI API (text-to-SQL) — Natural language query generation; optional LLM enhancement for developer experience.
• Cron (robfig/cron) — Scheduled background tasks (auto-audit, cleanup, report generation) without external job queue.

• Single-binary deployment (no separate frontend server)

  • Why: Simplifies distribution and reduces operational overhead for smaller DBA teams.
  • Consequence: Frontend and backend tightly coupled; harder to scale UI independently; frontend assets compiled into binary.

• In-process rule evaluation (no remote policy engine)

  • Why: Lower latency for audit decisions; no network round-trip per query.
  • Consequence: Rule changes require service restart; no fine-grained audit trail of rule evaluation logic.

• MySQL-only support (no PostgreSQL/Oracle)

  • Why: Focused scope; deeper MySQL-specific features (OSC, replication awareness).
  • Consequence: Cannot audit non-MySQL databases; effort to support new databases is substantial.

• Email-only notifications (no webhooks/Slack)

  • Why: Universal compatibility across enterprises; no external service dependencies.
  • Consequence: Missing real-time alerting; slower feedback loop for urgent approval requests.

• Real-time query monitoring or continuous statement profiling (point-in-time audit only)
• Support for non-MySQL databases (PostgreSQL, Oracle, SQL Server)
• Automatic query remediation or rewriting (audit and approval only; execution is user-triggered)
• Multi-tenant isolation at the database layer (single-instance deployment model)
• GraphQL or REST API versioning (assumes stable schema)

config.toml must be present and correctly configured with MySQL credentials before ./Yearning install or ./Yearning run (no automatic defaults). Database migrations are idempotent but should be tested in staging first due to audit-critical data. AI features require OPENAI_API_KEY environment variable if enabled. LDAP/OIDC configuration in config.toml is optional but complex; test integration early. Timezone handling for audit logs depends on server OS timezone.

• SQL AST Parsing & Validation — Core to Yearning's audit engine (src/engine/engine.go); you must understand how SQL statements are parsed and validated against rules before execution
• Role-Based Access Control (RBAC) — Yearning's permission model restricts audit/query access by user role; critical for understanding authorization in handler middleware
• JWT (JSON Web Tokens) — Used for stateless authentication (via golang-jwt/jwt dependency); inspect token claims in src/handler/common/impl.go to understand session management
• LDAP & OIDC Authentication — Yearning supports enterprise auth (go-ldap, OIDC integration visible in docs); necessary for integrating with corporate identity providers
• Message Pack Serialization — Used via vmihailenco/msgpack for efficient data serialization in inter-service communication; check how audit logs are serialized
• Cron Job Scheduling — robfig/cron/v3 powers scheduled audit tasks and cleanup jobs; understand how background maintenance runs
• Anonymization & Encryption — Privacy-focused feature for masking sensitive query results (golang.org/x/crypto); inspect how PII is handled in query audit logs

• mysql-osc/pt-online-schema-change — Percona Toolkit's schema migration tool; solves the DDL execution problem that Yearning audits
• vitessio/vitess — MySQL middleware for query routing and schema management; alternative approach to SQL governance at proxy layer
• actiontech/sqle — Chinese alternative SQL audit platform with similar feature set (audit, rules, approval workflows)
• openai/openai-go — Official OpenAI Go SDK; directly used in src/handler/fetch/ai.go for AI-powered SQL optimization
• gorm/gorm — The ORM framework used throughout for all database operations; understanding GORM hooks is essential for audit logging

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/handler/manage/flow/flow.go

The flow.go file exists but flow_test.go appears minimal. SQL audit flow logic is critical for this platform - testing approval workflows, state transitions, and query validation would catch regressions early. This directly improves reliability of the core audit feature.

• [ ] Examine existing flow_test.go and identify untested branches in flow.go
• [ ] Add tests for workflow state transitions (pending → approved → executed)
• [ ] Add tests for query validation and rejection paths
• [ ] Add tests for concurrent flow operations using testify/assert
• [ ] Ensure >80% code coverage for flow logic

Add GitHub Actions workflow for Go security scanning and linting

The repo has docker-build-push.yml and check-issue.yml, but no automated Go linting/security scanning. Given this is a security-focused SQL audit tool handling sensitive queries, adding gosec, golangci-lint, and go vet checks in CI is critical to catch vulnerabilities before merge.

• [ ] Create .github/workflows/go-lint-security.yml
• [ ] Configure golangci-lint with strict rules for all src/ and cmd/ packages
• [ ] Add gosec to scan for security issues in SQL handling code
• [ ] Add go vet and go test with -race flag for concurrency issues
• [ ] Set workflow to run on every PR and push to main branch

Add unit tests for src/handler/login/login.go and OIDC authentication

Authentication handlers (login.go and oidcLogin.go) are critical security components with no visible test coverage. SQL audit platforms must have robust auth - testing JWT validation, LDAP/OIDC flows, and session handling prevents auth bypasses.

• [ ] Create src/handler/login/login_test.go for standard login flows
• [ ] Add tests for JWT token validation and expiration using golang-jwt/jwt
• [ ] Create src/handler/login/oidcLogin_test.go for OIDC provider interactions
• [ ] Mock LDAP and OIDC external calls using github.com/stretchr/testify/mock
• [ ] Test edge cases: invalid tokens, expired sessions, malformed credentials

• Add unit tests for src/handler/common/expr.go (expression evaluation logic) — currently no test file exists and expression parsing is critical for audit rules
• Implement missing permission checks in src/apis/query.go — verify that RBAC controls are enforced at every endpoint before returning query results
• Document the Check Rules schema in docs/ with examples from src/engine/engine.go — the README mentions rule support but provides no concrete examples or config format guide

• High · Outdated Go Version and Potential Dependencies — go.mod, .github/workflows/. The project targets Go 1.21 with toolchain 1.22.2. Several dependencies may have known vulnerabilities. The go-openai package (v1.36.1) and other packages should be regularly audited. No evidence of dependency vulnerability scanning in CI/CD pipeline. Fix: Implement automated dependency scanning using tools like 'go list -m all | nancy', Dependabot (partially configured), or Snyk. Update Go to latest stable version (1.22+). Add regular security audits to CI/CD pipeline.
• High · Potential SQL Injection Vulnerabilities — src/apis/query.go, src/handler/fetch/fetch.go, src/handler/order/. As a SQL audit platform, the codebase handles raw SQL queries. The presence of src/handler/fetch/fetch.go and src/apis/query.go suggests direct SQL query processing. Without evidence of parameterized queries or ORM safety measures throughout, there's risk of SQL injection attacks. Fix: Conduct thorough code review of all SQL handling. Enforce parameterized queries/prepared statements. Use ORM (GORM is present) exclusively for database operations. Implement input validation and sanitization for all user-supplied SQL. Add SQL injection detection rules.
• High · JWT Implementation Risk — go.mod, src/handler/login/. The project uses github.com/golang-jwt/jwt v3.2.2+incompatible, which is an older/deprecated version. This JWT library version has known vulnerabilities and is not the recommended golang-jwt package. Fix: Migrate to github.com/golang-jwt/jwt/v5 (latest version). Review JWT secret management - ensure secrets are not hardcoded and use strong, randomly generated keys. Implement proper token expiration and refresh mechanisms.
• High · Missing HTTPS/TLS Configuration Visibility — conf.toml.template, main.go, docker/docker-compose.yml. No evidence of TLS configuration in visible config files (conf.toml.template). The application handles sensitive database credentials and audit logs which should always be encrypted in transit. Fix: Enforce HTTPS/TLS for all communications. Configure SSL certificates in production. Document TLS setup in configuration template. Implement HSTS headers. Review docker-compose for secure port configurations.
• High · LDAP Injection Risk — src/handler/login/oidcLogin.go, src/handler/login/login.go. The project uses LDAP for authentication (src/handler/login/oidcLogin.go, go-ldap/v3). LDAP queries constructed with user input are vulnerable to LDAP injection attacks. Fix: Use parameterized LDAP queries. Implement LDAP filter escaping (ldap.EscapeFilter). Validate and sanitize all user inputs before LDAP queries. Add unit tests for LDAP injection scenarios.
• High · Insecure Cryptographic Dependency — go.mod, src/handler/login/. golang.org/x/crypto v0.28.0 is present but older versions of this package contained vulnerabilities. Regular updates are critical for cryptographic libraries. Fix: Update golang.org/x/crypto to latest version (0.30.0+). Implement automated dependency updates. Audit cryptographic usage - ensure proper algorithms for hashing passwords (bcrypt/scrypt, not MD5/SHA1).
• Medium · Potential XSS Vulnerabilities in Frontend — src/handler/ (all handlers with UI output). The project appears to have a web interface. Without visible frontend code review, template injection and XSS risks exist when rendering SQL queries, audit logs, and user-generated content. Fix: Implement output encoding/escaping for all user-controlled data in templates. Use security-focused template engines. Implement Content Security Policy (CSP) headers. Regular frontend security audits and OWASP Top 10 reviews.
• Medium · Missing Authentication in Some APIs — undefined. src/apis/dash.go, src/apis/fetch.go, src/apis/query.go may expose endpoints without proper authentication checks, as no authorization middleware is visible in file structure. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.