@logicseek/hello-cc 0.1.5 → 0.1.6

package/docs/README.md

@@ -22,3 +22,5 @@ summary and first command. Use these docs when you need more detail.
   levels, coordination semantics, and provider-session binding.
 - [Implementation Notes](implementation.md): architecture, protocol, command
   surface, stack, shim behavior, and implementation plan.
+- [Architecture](architecture.md): target project layout, module boundaries,
+  dependency direction, and staged migration plan.

package/docs/README.zh-CN.md

@@ -20,5 +20,7 @@
 - [设计说明](design.md)：产品边界、项目边界、能力层级、协作语义和 provider
   session 绑定。
 - [实现说明](implementation.md)：架构、协议、命令面、技术栈、shim 行为和实现计划。
+- [架构设计](architecture.zh-CN.md)：目标目录结构、模块边界、依赖方向和分阶段
+  迁移计划。
 
-设计和实现文档目前只有英文版。
+`design.md` 和 `implementation.md` 目前只有英文版。

package/docs/architecture-split-review.md

@@ -0,0 +1,217 @@
+# Architecture Split Review
+
+Date: 2026-06-14
+
+This review covers the local commits on `master` that are ahead of
+`origin/master` after `0.1.5`.
+
+It is written from the separate review branch
+`arch-review/split-layout-from-origin`. The main worktree is intentionally left
+untouched because other peers may still be finishing scoped implementation work.
+
+## Recommendation
+
+Keep the current architecture direction. Do not merge the new product-boundary
+modules back into `bin/hcc.mjs`, and do not collapse them into another large
+generic helper file.
+
+If the goal is to publish or synchronize soon, keep the current local commit
+history and add one or more cleanup commits. Those cleanup commits should focus
+on remaining boundary issues and compatibility-shim policy.
+
+If the goal is clean commit history, rebuild the stack in a separate worktree
+from `origin/master`. Do not rewrite the active `master` worktree while peers
+are coordinating through it.
+
+## What Happened
+
+The first local split commits were mostly flat helper extraction from
+`bin/hcc.mjs` into top-level `lib/*.mjs` files. They reduced the entrypoint size
+but did not yet express the product architecture:
+
+- provider and tmux helpers
+- lock and team planning helpers
+- peer identity, peer format, and peer binding helpers
+- project registry and project context helpers
+- handoff, timeline, runtime state, task liveness, automation, and render helpers
+- help text, message store, runtime request, task store, task CLI, and
+  coordination-state helpers
+
+Later commits introduced `docs/architecture.md` and started moving primary
+implementations into product boundaries:
+
+- `lib/core/coordination`
+- `lib/core/peers`
+- `lib/core/sessions`
+- `lib/db`
+- `lib/db/stores`
+- `lib/runtime`
+- `lib/terminal`
+- `lib/web`
+- `lib/integrations`
+- `lib/release`
+- `lib/shared`
+- `lib/ui`
+
+That second phase is the correct direction.
+
+## Keep
+
+These boundaries are worth keeping as the primary implementation shape:
+
+- `lib/core/coordination/*` for product coordination semantics.
+- `lib/core/peers/*` for pure peer semantics.
+- `lib/db/schema.mjs` and `lib/db/stores/*` for SQLite schema and stores.
+- `lib/runtime/*` for runtime files, runtime client access, project registry,
+  and project context.
+- `lib/terminal/tmux.mjs` for tmux adapter behavior.
+- `lib/web/*` for Web runtime, HTTP helpers, peer actions, and UI template.
+- `lib/integrations/*` for provider, hook, shim, and process integration
+  details.
+- `lib/release/*` for release metadata and release-note logic.
+- `lib/shared/*` only for small dependency-light utilities.
+- `lib/ui/*` for text/help/state rendering.
+
+## Cleanup Candidates
+
+The remaining cleanup should be deliberate, not another broad helper extraction.
+
+### Top-Level Compatibility Shims
+
+Many top-level `lib/*.mjs` files are now compatibility re-export shims. Examples
+include `lib/tmux.mjs`, `lib/provider-commands.mjs`, `lib/web-runtime.mjs`,
+`lib/web-http.mjs`, `lib/web-ui-template.mjs`, `lib/task-store.mjs`,
+`lib/messages.mjs`, `lib/locks.mjs`, `lib/db-schema.mjs`, and
+`lib/session-launch.mjs`.
+
+Before publish:
+
+- Treat the installed CLI commands as the public API. Do not document new
+  `@logicseek/hello-cc/lib/*` imports as user-facing API.
+- `@logicseek/hello-cc@0.1.5` is already published from git head `4969100`, and
+  that package exposed several top-level `lib/*.mjs` helper paths because the
+  package includes `lib/` and has no `exports` map.
+- Keep already-published top-level `lib/*.mjs` paths as compatibility
+  re-exports for at least one release cycle unless the project explicitly
+  chooses a breaking package-surface change.
+- For compatibility shims added only in local commits after `0.1.5`, either
+  remove them before the next publish or document them in the release notes as
+  compatibility-only and revisit removal before the following release.
+- Do not let compatibility shims become the target architecture. Primary
+  implementations should live under the product-boundary directories.
+
+Classify top-level shims before release:
+
+- Group A: already-published or CLI-facing helper paths that stay stable for
+  this release.
+- Group B: migration compatibility paths that re-export moved implementations;
+  keep only if needed and describe them as compatibility-only deep-import paths.
+- Group C: unpublished shims with no internal use and no compatibility value;
+  remove before publishing.
+
+### CLI Boundary
+
+`bin/hcc.mjs` is smaller but still mixes command dispatch, command handlers, Web
+startup, session lifecycle, and terminal/Web orchestration. Future work should
+move by command or subsystem boundary, not by helper name.
+
+Good next boundaries:
+
+- `lib/cli/args.mjs`
+- `lib/cli/context.mjs`
+- `lib/cli/dispatch.mjs`
+- `lib/cli/commands/*`
+
+### Regression Runner
+
+`scripts/regression.mjs` has grown too large. It should become a runner over
+domain-specific files:
+
+- `scripts/regression/cli.mjs`
+- `scripts/regression/db.mjs`
+- `scripts/regression/runtime.mjs`
+- `scripts/regression/web.mjs`
+- `scripts/regression/integrations.mjs`
+- `scripts/regression/release.mjs`
+
+This should be done after the current layout work is stable, because regression
+coverage is the safety net for the refactor.
+
+### Setup, Discover, Guidance, and Shims
+
+`lib/setup.mjs`, `lib/discover.mjs`, `lib/guidance.mjs`, and
+`lib/shim-script.mjs` still carry mixed responsibilities. Continue splitting
+these by product boundary:
+
+- hooks under `lib/integrations/hooks*`
+- shims under `lib/integrations/shims*`
+- shell and terminal adapters under `lib/terminal`
+- runtime/project concerns under `lib/runtime`
+- guidance text generation under `lib/ui` or a dedicated guidance boundary
+
+### Handoff Boundary
+
+`lib/handoff.mjs` is still a top-level helper. Decide whether it belongs in
+`lib/core/coordination/handoff.mjs` as product semantics or under
+`lib/cli/commands/handoff.mjs` if it is mostly CLI formatting and file listing.
+
+## Branch Strategy
+
+Use one of two paths.
+
+Path A: publish-oriented cleanup
+
+1. Keep current `master` history.
+2. Add focused cleanup commits.
+3. Run full regression, release checks, GitHub release dry-run, and pack dry-run.
+4. Publish/synchronize only after the cleanup decision is complete.
+
+Path B: clean-history rebuild
+
+1. Keep `master` untouched.
+2. Use a separate worktree from `origin/master`.
+3. Rebuild the split as fewer architectural commits:
+   - architecture docs
+   - core coordination and peer semantics
+   - db schema/stores
+   - runtime/project/session helpers
+   - terminal adapters
+   - web runtime and UI
+   - integrations providers/hooks/shims
+   - release/shared/ui helpers
+   - regression restructuring
+4. Run full regression and release checks before replacing the active stack.
+
+## Current Decision
+
+The safer default is Path A: keep current history and add cleanup commits.
+
+Choose Path B only if the project explicitly values a clean local commit stack
+more than the time and risk of rebuilding and revalidating the entire series.
+
+The current safety refs are:
+
+- `safety/layout-split-20260614-at-ffc42a7`, protecting the earlier split stack.
+- `safety/layout-split-20260614-at-11fd4f6`, protecting the split stack through
+  `11fd4f6` before this package-surface policy update.
+
+Because `0.1.5` is already on npm, the next publish that includes the current
+local commits must bump the package version. Do not republish `0.1.5`.
+
+## Coordination Notes
+
+Continue finishing any already-started layout lanes that are clearly correcting
+the architecture boundary. For example, moving setup hooks and shim
+implementation into `lib/integrations` is still part of the same boundary
+cleanup, not a new random helper extraction.
+
+After those active lanes finish, pause new implementation splits and make a
+cleanup decision:
+
+1. Decide whether this review document should be copied into `master` as a
+   durable design record.
+2. Decide whether top-level compatibility shims are public for this release.
+3. If shims are kept, document that they are compatibility paths.
+4. If shims are removed, do it before publish and run full pack/release checks.
+5. Do not start broad `bin/hcc.mjs` command extraction or regression runner
+   splitting until the shim policy is settled.

package/docs/architecture.md

@@ -0,0 +1,385 @@
+# hello-cc Architecture
+
+Date: 2026-06-14
+
+This document defines the intended module layout for hello-cc. It is a design
+target for future refactors, not a claim that every file already follows this
+layout.
+
+The goal is to stop splitting code by helper size and start moving code by
+product boundary. A thin CLI, explicit core state model, dedicated runtime
+layer, terminal adapters, and Web server boundary make future changes easier to
+review and less likely to mix unrelated behavior.
+
+## Reference Shape
+
+The target shape follows the same broad separation used by mature agent CLI
+projects:
+
+- entrypoints stay small and delegate to command or server packages;
+- core coordination logic is independent from HTTP, tmux, and process launch;
+- runtime files and runtime clients live outside the command handlers;
+- Web server routes, WebSocket transport, and session lifecycle are explicit
+  server modules;
+- provider-specific behavior is isolated from generic session and task logic;
+- tests are grouped by domain instead of appended to one large script forever.
+
+In particular, Codex-style layouts separate `cli`, `core`, `app-server`,
+`protocol` or transport, state stores, hooks, config, and execution adapters.
+hello-cc does not need Rust crates or the same scale, but it should use the same
+architectural idea: split by boundary, not by convenience.
+
+## Current Pressure Points
+
+The codebase has already extracted many focused modules under `lib/`, including
+schema, runtime state, task/message stores, peer identity, provider command
+building, tmux helpers, Web HTTP helpers, and render helpers.
+
+The remaining structural pressure is mostly:
+
+- `bin/hcc.mjs` still contains command dispatch, command handlers, Web server
+  setup, HTTP routes, WebSocket terminal handling, tmux session management, PTY
+  session management, external buffer adoption, and shutdown cleanup.
+- `cmdWeb()` is the largest mixed boundary. It should be treated as a Web
+  runtime subsystem, not as a normal CLI command body.
+- `scripts/regression.mjs` is a valuable full regression gate, but it should
+  eventually become a runner over domain-specific regression modules.
+
+## Target Layout
+
+```text
+bin/
+  hcc.mjs
+
+lib/
+  cli/
+    dispatch.mjs
+    context.mjs
+    commands/
+      ask.mjs
+      broadcast.mjs
+      down.mjs
+      event.mjs
+      gc.mjs
+      handoff.mjs
+      hooks.mjs
+      init.mjs
+      inject.mjs
+      join.mjs
+      lock.mjs
+      msg.mjs
+      peer.mjs
+      prompt.mjs
+      run.mjs
+      scan.mjs
+      setup.mjs
+      shim.mjs
+      state.mjs
+      status.mjs
+      task.mjs
+      team.mjs
+      uninstall.mjs
+      update.mjs
+      up.mjs
+      web.mjs
+
+  core/
+    coordination/
+      automation.mjs
+      handoff.mjs
+      locks.mjs
+      messages.mjs
+      tasks.mjs
+      teams.mjs
+      timeline.mjs
+    peers/
+      bindings.mjs
+      format.mjs
+      identity.mjs
+      liveness.mjs
+    sessions/
+      launch.mjs
+      model.mjs
+      providers.mjs
+      serialization.mjs
+
+  db/
+    connection.mjs
+    migrations.mjs
+    schema.mjs
+    stores/
+      locks.mjs
+      messages.mjs
+      peers.mjs
+      tasks.mjs
+
+  runtime/
+    client.mjs
+    paths.mjs
+    projects.mjs
+    state.mjs
+
+  terminal/
+    external-buffer.mjs
+    pty.mjs
+    tmux-stream.mjs
+    tmux.mjs
+
+  web/
+    projects.mjs
+    routes.mjs
+    server.mjs
+    session-manager.mjs
+    websocket.mjs
+    http.mjs
+    ui-template.mjs
+
+  integrations/
+    hooks/
+      claude.mjs
+      codex.mjs
+    providers/
+      claude.mjs
+      codex.mjs
+      shell.mjs
+    shims/
+      setup.mjs
+      script.mjs
+
+  ui/
+    format.mjs
+    help.mjs
+    state-render.mjs
+
+  release/
+    package-meta.mjs
+    release-notes.mjs
+
+  shared/
+    errors.mjs
+    json-file.mjs
+    text.mjs
+
+scripts/
+  regression.mjs
+  regression/
+    cli.mjs
+    coordination.mjs
+    db.mjs
+    release.mjs
+    runtime.mjs
+    sessions.mjs
+    web.mjs
+```
+
+## Boundary Rules
+
+`bin/hcc.mjs` should become a thin entrypoint. It may parse global arguments,
+create the root context, invoke dispatch, and convert top-level errors to CLI
+output. It should not own Web routing, DB schema, tmux streaming, provider
+command construction, or task state machines.
+
+`lib/cli/` owns command parsing and command handlers. A command handler can
+open a database, call stores or core services, and print results. It should not
+contain reusable domain logic when that logic can live in `core`, `runtime`,
+`terminal`, `web`, or `integrations`.
+
+`lib/core/` owns product semantics. Task lifecycle, takeover readiness, message
+threading, lock conflict rules, team planning, peer identity semantics, and
+session identity rules belong here. Core modules should not depend on HTTP
+request objects, WebSocket objects, tmux commands, or process spawning.
+
+`lib/db/` owns SQLite connection, schema, migrations, and data stores. Store
+modules should expose explicit operations and transaction boundaries. Schema
+migrations must be safe to run for every registered project database, not just
+the current project.
+
+`lib/runtime/` owns runtime files, runtime discovery, runtime client requests,
+and project registry state. It should not know how Web routes render UI or how
+terminal bytes are transported.
+
+`lib/terminal/` owns terminal adapters. tmux pane inspection, tmux stream setup,
+tmux input, PTY spawning, and external buffer adoption belong here. Terminal
+adapters can emit session events, but they should not decide task ownership or
+message behavior.
+
+`lib/web/` owns the Web runtime. It should assemble project context, session
+manager, HTTP routes, WebSocket terminal upgrade, and shutdown cleanup. Route
+handlers should be small and delegate to stores, core services, runtime
+modules, or terminal/session manager methods.
+
+`lib/integrations/` owns provider-specific behavior. Claude, Codex, and shell
+command construction, hook installation details, and shim scripts should stay
+out of generic session and coordination modules.
+
+`lib/ui/` owns CLI-facing text output and help. It can format already-computed
+state, but it should not read or mutate project state.
+
+`lib/release/` owns release metadata and release notes helpers. Release scripts
+and GitHub release tooling should share these helpers.
+
+`lib/shared/` is only for small, dependency-light utilities used across several
+boundaries. It should not become a dumping ground.
+
+## Package Surface Policy
+
+The supported public interface is the installed CLI: `hcc` and `hello-cc`.
+`package.json` includes `lib/` because the CLI imports those files at runtime,
+not because every `lib/*` path is a stable library API.
+
+Do not document new user workflows that import `@logicseek/hello-cc/lib/*`.
+Primary implementations should live in the target product directories, and
+top-level `lib/*.mjs` files should be treated as compatibility entrypoints only
+when there is a concrete compatibility reason.
+
+`@logicseek/hello-cc@0.1.5` has already been published from git head
+`4969100`. That published package exposed several top-level `lib/*.mjs` helper
+paths because the package does not define an `exports` map. Do not remove or
+rename those already-published paths in a routine cleanup commit; keep them as
+compatibility re-exports for at least one release cycle unless the project
+explicitly chooses a breaking package-surface change.
+
+For local migration commits after `0.1.5`, avoid adding more top-level
+compatibility shims by default. If an unpublished top-level shim is kept for the
+next release, mention it in the release notes as compatibility-only and revisit
+whether it can be removed before the following release. Do not let
+compatibility shims become the target architecture.
+
+Before release, classify top-level `lib/*.mjs` paths into three groups:
+
+- Group A: already-published or CLI-facing helper paths that must stay stable
+  for this release.
+- Group B: migration compatibility paths that re-export moved implementations;
+  keep them for one release if needed, but describe them as compatibility-only
+  deep-import paths.
+- Group C: unpublished shims with no internal use and no compatibility value;
+  remove these before publishing.
+
+Because `0.1.5` is already on npm, any release that includes local commits after
+`4969100` must use a new package version. Do not try to republish `0.1.5`.
+
+## Dependency Direction
+
+The intended dependency direction is:
+
+```text
+bin -> cli -> web/runtime/db/core/terminal/integrations/ui
+web -> runtime/db/core/terminal/ui
+terminal -> shared/core sessions only when needed
+core -> shared
+db -> shared
+ui -> shared
+release -> shared
+```
+
+Avoid these dependencies:
+
+- `core` importing `web`, `terminal`, `cli`, or `integrations`;
+- `db` importing `cli` or `web`;
+- `terminal` importing Web route modules;
+- provider integrations importing command handlers;
+- `shared` importing product-specific modules.
+
+This keeps most behavior testable without a Web runtime or tmux process.
+
+## Migration Plan
+
+Refactor in small, reviewable phases. Each phase should keep public behavior and
+npm package contents stable unless the task explicitly says otherwise.
+
+1. Document the target architecture.
+   This document is the contract for future splits.
+
+2. Move existing flat modules into target directories.
+   Start with low-risk moves such as `runtime-*`, `web-*`, `task-store`,
+   `messages`, `help`, `state-render`, and release helpers. Keep compatibility
+   re-export files temporarily if the import churn becomes too large.
+
+3. Split the Web runtime by subsystem.
+   Extract project selection, session manager, Web routes, WebSocket terminal
+   handling, tmux stream, PTY session, and external buffer adoption from
+   `cmdWeb()` in separate commits.
+
+4. Make `bin/hcc.mjs` a thin entrypoint.
+   Move dispatch and command groups under `lib/cli/commands/`.
+
+5. Split regression tests by domain.
+   Keep `npm test` as the single full regression command, but make it call
+   focused domain modules under `scripts/regression/`.
+
+## Web Runtime Target
+
+The highest-value runtime split is:
+
+```text
+lib/web/server.mjs
+  createWebRuntime(ctx, opts, deps)
+  start/stop lifecycle
+
+lib/web/projects.mjs
+  rememberProject()
+  knownProjects()
+  projectFromRequest()
+
+lib/web/session-manager.mjs
+  sessions map
+  getSession()
+  serializeSession()
+  startSession()
+  stopSession()
+  restoreManagedSessions()
+
+lib/web/routes.mjs
+  routeHttpRequest(req, res, env)
+
+lib/web/websocket.mjs
+  handleTerminalUpgrade(req, socket, head, env)
+
+lib/terminal/tmux-stream.mjs
+  startTmuxStream()
+  stopTmuxStream()
+  refreshTmuxSnapshot()
+
+lib/terminal/external-buffer.mjs
+  adoptExternalSession()
+  scanExternalSessions()
+```
+
+This split makes Web blank-screen, stale session, tmux stream, and provider
+binding bugs easier to isolate.
+
+## Testing Expectations
+
+Every structural migration should run:
+
+```bash
+git diff --check
+node --check bin/hcc.mjs
+node --check <changed modules>
+npm test
+```
+
+Release-facing changes should also run:
+
+```bash
+npm run release:check
+npm run release:github:dry-run
+npm pack --dry-run --json
+```
+
+When new modules are added under `lib/`, verify that `npm pack --dry-run --json`
+includes them.
+
+## Non-Goals
+
+Do not introduce TypeScript, Rust, a bundler, or a build step as part of this
+layout migration. Those are separate product decisions with release and install
+costs.
+
+Do not rewrite working behavior while moving files. Directory migration commits
+should be boring: imports change, module paths change, regression guards
+change, behavior stays the same.
+
+Do not move UI template assets into a framework until there is a separate Web UI
+build plan. The current npm package should remain directly runnable after
+install.