Skip to content

README.md

Latest commit

 

History

History
164 lines (116 loc) · 9.04 KB

README.md

File metadata and controls

164 lines (116 loc) · 9.04 KB
Raw

Adonis.js Reimplementation Charter

Status

Discovery and architecture proposal. No production implementation has started.

Baseline inspected: PackmindHub/packmind@0da8745c7eb7ecb4e137131aa72756180eff2b30 on 2026-07-28.

Goal

Reimplement the public Packmind application incrementally with AdonisJS while preserving observable OSS behavior and keeping the existing frontend and CLI compatible during migration.

The target is one deployable modular monolith with independently testable business modules, explicit ports and adapters, domain-driven boundaries, strict RED-GREEN-REFACTOR, and the Adonis IoC container as the only composition root.

Non-goals

  • No big-bang rewrite.
  • No mechanical NestJS-to-Adonis controller translation.
  • No direct port of every historical TypeORM migration to Lucid without a data strategy.
  • No claim of Enterprise feature parity: several implementations are absent from the public repository.
  • No new generic registry, service locator, or oversized shared package.
  • No frontend redesign during backend parity work.

Evidence-based size

The inspected repository contains approximately:

  • 4,012 tracked files.
  • 23 Nx packages.
  • 3,156 TypeScript files.
  • 496 to 534 test files, depending on inclusion rules.
  • 29 API controllers and roughly 145 HTTP handlers.
  • 68 frontend route modules.
  • About 40 application persistence schemas and 124 business migrations.
  • 38 CLI command files and 16 root CLI commands.
  • 9 GitHub Actions workflows.
  • 34 public MDX documentation pages.

A realistic OSS-parity estimate is 56–89 person-weeks for a team already competent with TypeScript, Adonis, DDD and migration work. This excludes a frontend redesign and complete reconstruction of unavailable proprietary modules. A solo implementation should expect a multi-quarter programme, not a framework sprint.

Product surfaces to preserve

  1. Web API under the current /api/v0 contract.
  2. React frontend behavior and payload expectations.
  3. Distributed Packmind CLI compatibility.
  4. PostgreSQL data and tenant isolation.
  5. Redis-backed cache, jobs and SSE behavior where externally observable.
  6. GitHub and GitLab integrations.
  7. Coding-agent rendering for AGENTS.md, Claude, Cursor, Copilot, Codex, OpenCode, Continue, Junie, GitLab Duo and source formats.
  8. Docker, release, documentation and operational workflows.

Candidate bounded contexts

Identity and Tenancy

Users, authentication, social login, invitations, password reset, API keys, CLI login codes, organizations and organization membership.

Spaces and Authorization

Spaces, visibility, membership, roles, pinned spaces, global space and access policies. Tenant and space isolation must be enforced below HTTP controllers and covered by negative database tests.

Playbook

The core artifact library: Standards, Commands and Skills, their immutable versions, rules, examples, files, slugs, moves and soft deletion. These remain separate aggregates inside one coherent context unless implementation evidence requires independent modules.

Governance

Change proposals, review, accept/reject, conflicts, outdated versions, audit and application of approved changes.

Packages and Distribution

Packages, artifact membership, targets, deployment requests, distributed versions, history, drift, dashboards and progress.

Agent Rendering

Pure, deterministic conversion of canonical artifacts to agent-specific file sets, including merge markers, scopes, default skills, previews and lockfiles.

Source Control

GitHub PAT/App, GitLab, repositories, branches, remote files, commits, installation tokens and credential vaulting.

Quality and Intelligence

Linter execution, AST parsing, detection programmes, LLM configuration and provider adapters.

Marketplace and Plugins

Marketplace repositories, plugin rendering, rolling synchronization PRs, adoption and installation tracking. Public parity is blocked by proprietary implementation gaps.

Platform

Transactions, outbox/inbox, jobs, cache, SSE, clock, identifiers, encryption, logging, metrics and feature flags. This module contains no business vocabulary.

Main business flows

  1. Sign-up or invitation → organization/global space → CLI authentication.
  2. Create/version Standards, Commands or Skills → attach them to Packages.
  3. Install locally → render agent files → write lockfile → track distribution.
  4. Connect GitHub/GitLab → select target → render → commit → record distribution → notify through SSE.
  5. Stage local playbook changes → submit proposal → review → apply versioned changes.
  6. Define examples and detection hints → generate/test/activate deterministic linter programmes → execute through CLI.
  7. Configure an LLM provider → resolve an organization-scoped adapter without returning secrets through the API.

Work inventory

Workstream Main deliverables Estimate
Contract characterization OpenAPI baseline, errors, cookies, SSE, CLI and job contracts, golden fixtures 3–5 pw
Adonis foundation App bootstrap, providers, module rules, error mapping, configuration, health and architecture tests 3–5 pw
Identity, tenancy and spaces Authentication bridge, organizations, membership, policies, invitations, API keys 5–8 pw
Playbook Standards, rules, Commands, Skills, versions, files, move/delete/import 10–15 pw
Governance Change proposals, conflicts, decisions, audit and application 6–9 pw
Packages, distribution, rendering and Git Planning, snapshots, workers, renderers, source-control adapters, drift 10–16 pw
Quality and LLM AST/linter execution, sandboxing, provider configuration and adapters 6–10 pw
HTTP, CLI and jobs composition Compatible endpoints, Ace operations, distributed CLI contract, queue adapters 5–8 pw
Data migration and cutover Lucid baseline, dump validation, reconciliation, routing and rollback 6–10 pw
Security and operations Tenant tests, encryption, rate limits, metrics, traces, readiness and DLQ 5–8 pw

The rows overlap slightly in execution but represent 56–89 person-weeks in aggregate.

Critical unknowns

  • Proprietary implementations are absent for analytics, jobs, parts of linter generation, plugins/marketplaces, advanced spaces and playbook change management.
  • The public stubs are not evidence of complete OSS behavior.
  • Recipes-to-Commands compatibility still appears in routes and migrations.
  • No generated OpenAPI contract was found despite documentation references.
  • The final schema is spread across approximately 124 TypeORM migrations.
  • Distribution state semantics overlap across deployment, distribution, distributed package and target status.
  • Durable atomicity between database updates and Git publication is not guaranteed by the current in-memory event flow.
  • Secret encryption and rotation behavior requires explicit verification.
  • SSE ordering, reconnection and delivery guarantees need a compatibility decision.
  • Linter JavaScript sandbox limits, timeouts and memory constraints need a new threat model.

Top risks and controls

Risk Control
Hidden invariants in oversized use cases Characterization tests before extraction
Cross-tenant data exposure Mandatory tenant IDs in ports, policy checks, negative integration tests
API/CLI regression Contract fixtures and differential tests against the legacy runtime
Lost or duplicated side effects Transactional outbox/inbox, idempotency keys, retries and DLQ
Rendering regressions Golden files and shadow rendering before publication
Data corruption during migration Baseline from a fully migrated database and rehearsal on anonymized dumps
Endless dual runtime Capability-by-capability ownership and explicit retirement gates
IoC replaced by another service locator Adonis providers only; constructor injection everywhere else
DDD ceremony without isolation Architecture tests and public contracts per module
Proprietary scope accidentally promised Separate parity matrix: public evidence, hypothesis, excluded scope

Definition of done for every vertical slice

  1. User-visible Gherkin scenario written first.
  2. Unit or application test written and observed failing for the expected reason.
  3. Minimal implementation makes it pass.
  4. Adapter contract tests pass against memory and real infrastructure implementations.
  5. HTTP/job/CLI integration test passes.
  6. Architecture rules and full module suite pass.
  7. Tenant isolation, authorization, idempotence and failure behavior are covered where relevant.
  8. RED and GREEN commands are preserved in the pull request evidence.
  9. Documentation, migration and rollback notes are updated.
  10. No production code is merged without a prior failing test.

Immediate decision

Start with contract characterization, not an Adonis scaffold. The first migrated vertical slice should be read/create/version of a Standard because it exercises domain modeling, authorization, persistence, transactions, error mapping and HTTP compatibility without starting with the highest-risk distribution workflow.