diff --git a/src/lib/README.md b/src/lib/README.md new file mode 100644 index 00000000000..b7e9a4ece13 --- /dev/null +++ b/src/lib/README.md @@ -0,0 +1,57 @@ + + + +# `src/lib` layout + +`src/lib` is organized by architectural role first, then by product area. Use this map when adding new code or when moving legacy flat modules into clearer homes. + +## Primary layers + +```text +src/lib/commands/** oclif adapter classes and parser glue +src/lib/actions/** workflow orchestration and user-facing command behavior +src/lib/domain/** pure decisions, policy, classification, and planning +src/lib/adapters/** host boundaries: process, fs, Docker, OpenShell, HTTP +src/lib/state/** persisted local state and state-file I/O +src/lib/cli/** CLI framework, metadata, routing, and help infrastructure +src/lib/core/** tiny cross-cutting primitives with minimal dependencies +``` + +Layering rules: + +- Command classes should parse argv and call actions; they should not own product logic. +- Actions may compose domain helpers, adapters, state modules, and output. +- Domain helpers should stay pure and avoid direct process, filesystem, Docker, OpenShell, or network calls. +- Adapters isolate host-boundary calls so actions and tests can inject fakes. +- State modules own persisted local files and registry/session I/O. + +## Transitional feature folders + +Some older modules are still too large or coupled to split directly into actions/domain/adapters. Use these feature folders as intermediate homes while preserving behavior: + +```text +src/lib/agent/** agent definition, agent-specific onboarding, runtime helpers +src/lib/credentials/** credential storage and credential command support +src/lib/dashboard/** dashboard contract, health, and recovery helpers +src/lib/deploy/** deploy/build-image support that is not yet action-shaped +src/lib/diagnostics/** debug collection and diagnostic report helpers +src/lib/inference/** inference config, health probes, local runtime helpers +src/lib/messaging/** channel/messaging policy and message filtering helpers +src/lib/onboard/** onboarding support modules around the large legacy flow +src/lib/policy/** policy preset loading and application support +src/lib/runtime/** sandbox/runtime recovery helpers +src/lib/sandbox/** sandbox config, build, stream, and version support +src/lib/security/** redaction, secret patterns, and credential filtering +src/lib/shields/** shields orchestration, timers, and audit helpers +src/lib/tunnel/** local service/tunnel command support +``` + +Prefer small mechanical PRs that move one cluster at a time. High-import legacy files such as `onboard.ts`, `runner.ts`, `policies.ts`, `nim.ts`, and `services.ts` should either move late or keep temporary compatibility re-export files at their old paths. + +## Suggested migration sequence + +1. Document the target map and conventions before moving more code. +2. Move low-risk feature clusters such as `agent`, `dashboard`, `diagnostics`, and `shields`. +3. Move security/credentials/core helpers. +4. Move inference/model/local-runtime helpers. +5. Move onboarding support files before considering the large `onboard.ts` flow. diff --git a/src/lib/core/README.md b/src/lib/core/README.md new file mode 100644 index 00000000000..ae335e9fbd8 --- /dev/null +++ b/src/lib/core/README.md @@ -0,0 +1,20 @@ + + + +# Core helpers + +`src/lib/core` is for tiny cross-cutting primitives with minimal dependencies. These helpers should be safe to import from actions, domain modules, adapters, and CLI infrastructure. + +Good candidates: + +```text +version.ts +ports.ts +json-types.ts +errno.ts +wait.ts +url-utils.ts +shell-quote.ts +``` + +Keep product workflows out of this directory. If a helper starts depending on Docker, OpenShell, filesystem state, or a specific command workflow, move it to an adapter, action, domain area, or feature folder instead. diff --git a/src/lib/inference/README.md b/src/lib/inference/README.md new file mode 100644 index 00000000000..7f88e31744a --- /dev/null +++ b/src/lib/inference/README.md @@ -0,0 +1,25 @@ + + + +# Inference + +`src/lib/inference` is for model/provider configuration, inference health checks, local runtime support, and model catalog helpers. + +Suggested homes: + +```text +config.ts inference config parsing and normalization +health.ts inference endpoint health checks +local.ts local inference orchestration helpers +provider-models.ts provider model catalog support +model-prompts.ts prompt/model display helpers +nim.ts NIM catalog and lifecycle support +ollama/model-size.ts Ollama model size parsing +ollama/proxy.ts Ollama auth proxy support +ollama/windows.ts Windows Ollama support +vllm.ts vLLM support +web-search.ts web-search capability helpers +onboard-probes.ts onboarding-time inference validation probes +``` + +Longer term, pure inference decisions should move under `src/lib/domain/inference/**`, and HTTP/process boundaries should move under `src/lib/adapters/**`. diff --git a/src/lib/onboard/README.md b/src/lib/onboard/README.md new file mode 100644 index 00000000000..d54cba0b247 --- /dev/null +++ b/src/lib/onboard/README.md @@ -0,0 +1,28 @@ + + + +# Onboard support + +`src/lib/onboard` is the transitional home for onboarding support modules while the large legacy `src/lib/onboard.ts` flow is split over time. + +Good candidates: + +```text +types.ts +providers.ts +preflight.ts +usage-notice.ts +legacy-command.ts +``` + +Related modules may live outside this folder when their ownership is clearer: + +```text +src/lib/state/onboard-session.ts persisted onboarding session state +src/lib/inference/onboard-probes.ts inference validation probes used by onboarding +src/lib/inference/ollama/proxy.ts Ollama proxy lifecycle helpers +src/lib/inference/vllm.ts vLLM onboarding helpers +src/lib/inference/ollama/windows.ts Windows Ollama support +``` + +Do not move `src/lib/onboard.ts` casually. It is high-import and high-risk; if it moves, keep a compatibility re-export path or split it through focused behavior-preserving PRs. diff --git a/src/lib/sandbox/README.md b/src/lib/sandbox/README.md new file mode 100644 index 00000000000..3a1a4cc299f --- /dev/null +++ b/src/lib/sandbox/README.md @@ -0,0 +1,18 @@ + + + +# Sandbox support + +`src/lib/sandbox` is for sandbox configuration, build context, create-stream, version, and channel support that is not already owned by an action/domain module. + +Suggested homes: + +```text +config.ts sandbox config download/upload and mutation support +build-context.ts sandbox build context construction +create-stream.ts sandbox create progress parsing +version.ts sandbox/agent version helpers +channels.ts sandbox channel support, unless moved to messaging +``` + +Command workflows should continue to live under `src/lib/actions/sandbox/**`. Pure validation/classification helpers should live under `src/lib/domain/sandbox/**`. diff --git a/src/lib/security/README.md b/src/lib/security/README.md new file mode 100644 index 00000000000..3aeb1da673d --- /dev/null +++ b/src/lib/security/README.md @@ -0,0 +1,17 @@ + + + +# Security helpers + +`src/lib/security` is for reusable redaction, secret-pattern, credential-hash, and credential-filter helpers. + +Suggested homes: + +```text +credential-filter.ts +credential-hash.ts +redact.ts +secret-patterns.ts +``` + +Credential storage belongs under `src/lib/credentials/**`; security helpers should not own persistence or user prompts.