@trebired/code-server-kit 0.3.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 - nothing yet
 
+## 1.1.0
+
+- make the bundled `code-server` dependency the default resolution target
+- centralize package-resolution logic so preparation and installation discovery stay consistent
+- add coverage and documentation for single-package host integration without a direct `code-server` dependency
+
+## 1.0.0
+
+- expand the package from a session helper into a fuller generic `code-server` integration layer
+- add package preparation status and auto-repair helpers for the installed `code-server` dependency
+- add richer integration planning, diagnostics normalization, redaction, and proxy websocket helpers
+- add profile snapshot and deduplicated persistence helpers
+- strengthen session lifecycle ownership with inflight dedup, richer status metadata, and persisted diagnostics
+- expand systemd helpers with restart, journal summarization, and structured failure extraction
+
 ## 0.3.0
 
 - expand the package from launch planning into a full generic `code-server` session runtime

package/README.md

@@ -1,52 +1,39 @@
 # @trebired/code-server-kit
 
-Framework-agnostic `code-server` session runtime for Node.js applications.
+Framework-agnostic `code-server` integration layer for Node.js applications.
 
-`@trebired/code-server-kit` is the generic Trebired package for owning the full `code-server` lifecycle on Linux-first hosts:
+`@trebired/code-server-kit` is the generic Trebired package for owning the real `code-server` integration lifecycle on Linux-first hosts:
 
-- resolve the installed `code-server`
-- build launch plans and sandbox-friendly execution specs
-- restore and persist allowlisted profile data
-- launch directly or through transient systemd services
-- supervise readiness and startup failures
-- reuse, stop, restart, and inspect sessions with structured metadata
+- package preparation and bootstrap repair
+- installation and support-root resolution
+- launch and sandbox path planning
+- direct and transient systemd launching
+- session reuse, restart, stop, and status refresh
+- startup diagnostics and redaction
+- allowlisted profile restore and persistence
+- proxy-facing helpers for forwarded and websocket headers
 
-The package stays generic on purpose. It does not know about products, repositories, organizations, users, routes, or app-specific filesystem conventions.
+The package stays generic on purpose. It does not know about products, repositories, organizations, routes, or app-specific filesystem conventions.
 
 ## Install
 
 Runtime target: Node.js 22+ on Linux first.
 
 ```sh
-npm install @trebired/code-server-kit code-server
+npm install @trebired/code-server-kit
 ```
 
-## What Host Apps Still Provide
+`code-server` is installed as a normal dependency of this package. A host application only needs a separate direct `code-server` dependency when it intentionally wants to override how resolution happens.
 
-After the session runtime layer is in place, host applications mostly choose policy:
+By default, the package resolves and prepares its own bundled `code-server`. A host does not need to pass `resolveFrom` just to make normal session startup work.
 
-- `sessionKey`
-- `stateRoot`
-- `workspacePath`
-- `trustedOrigins`
-- `launchStrategy`
-- systemd `scope` when using systemd
-- optional profile roots
-- optional logging and policy hooks
+## Preferred Flow
 
-The package owns the generic mechanics:
+The preferred host integration flow is now:
 
-- installation resolution
-- entrypoint resolution
-- `node <entry.js>` vs direct executable launch
-- runtime profile directory defaults
-- direct launch vs systemd launch translation
-- readiness probing
-- session reuse checks
-- session metadata persistence
-- startup diagnostics normalization
-
-## Quick Start
+1. Create a session manager.
+2. Start a session with `sessionKey`, `stateRoot`, `workspacePath`, and trusted origins.
+3. Let the package prepare `code-server`, restore profile data, choose launch mechanics, supervise readiness, and persist diagnostics.
 
 ```ts
 import {
@@ -58,7 +45,6 @@ const sessions = createCodeServerSessionManager({
 });
 
 const started = await sessions.start({
-  launchStrategy: "direct",
   sessionKey: "workspace-42",
   stateRoot: "/srv/code-server-state",
   trustedOrigins: [
@@ -82,11 +68,41 @@ await sessions.stop({
 });
 ```
 
-## Main Session APIs
+The host application only needs a separate direct `code-server` dependency for explicit override scenarios, such as testing against a different installation root or intentionally pinning resolution outside `@trebired/code-server-kit`.
+
+## What The Package Owns
+
+High-level APIs now own generic mechanics that host apps previously had to rebuild:
+
+- checking whether the installed `code-server` package is fully prepared
+- running the package-owned bootstrap script when preparation is repairable
+- resolving the true entrypoint and support root
+- deriving support-tree read-only bind suggestions
+- deciding `node <entry.js>` vs direct execution
+- preparing profile directories and syncing only allowlisted items
+- handling missing optional native watchdog support with a non-fatal fallback mode
+- deduplicating concurrent starts for the same `sessionKey`
+- reusing healthy sessions when the effective spec still matches
+- invalidating stale sessions and restarting cleanly when the spec changes
+- collecting and sanitizing startup diagnostics
+- translating launch plans into transient systemd unit arguments
+
+Host applications mostly provide:
+
+- `sessionKey`
+- `stateRoot`
+- `workspacePath`
+- `trustedOrigins`
+- `launchStrategy`
+- systemd `scope` when using systemd
+- optional profile and sanitization policy
+- optional logging
+
+## Main High-Level APIs
 
 ### `createCodeServerSessionManager(options?)`
 
-Creates the main high-level lifecycle object and wires logging through `@trebired/logger-adapter`.
+Creates the main lifecycle object.
 
 Manager methods:
 
@@ -98,120 +114,81 @@ Manager methods:
 
 ### `startCodeServerSession(options)`
 
-One-shot helper that creates a manager and starts a session.
-
-Lifecycle-managed session APIs require:
-
-- `sessionKey`
-- `stateRoot`
+One-shot helper around the session manager.
 
 Defaults:
 
 - `launchStrategy` defaults to `"direct"`
-- reuse defaults to exact normalized spec match
-- `dataRoot` defaults to `stateRoot/sessions/<sessionKey>/runtime`
-- systemd never defaults its scope
-
-### `stopCodeServerSession(options)`
-
-Stops a direct child process or a systemd transient unit using the stored session metadata. If profile persistence is configured, the package persists allowlisted profile items after stop.
-
-### `restartCodeServerSession(options)`
-
-Runs stop then start with the same session request shape.
+- preparation defaults to auto-ensure
+- exact-spec inflight starts join each other
+- conflicting inflight starts fail with a structured conflict error
+- profile restore defaults to `"if-missing-or-empty"`
+- profile persist defaults to `"if-changed"`
 
 ### `getCodeServerSessionStatus(options)`
 
-Loads the package-owned session record and re-probes the live backing resource instead of trusting disk alone.
-
-### `readCodeServerSessionDiagnostics(options)`
+Returns a refreshed status object with:
 
-Reads the persisted diagnostics snapshot for a session.
+- `state`
+- `health`
+- `ready`
+- `preparation`
+- `watchdogMode`
+- `lastStartSummary`
+- `sanitizedDiagnostics`
 
-## Session Metadata
+### `readCodeServerSessionDiagnostics(options)`
 
-The package stores generic lifecycle metadata under:
+Reads the persisted diagnostics snapshot under:
 
 - `<stateRoot>/sessions/<safe-session-key>/session.json`
 - `<stateRoot>/sessions/<safe-session-key>/diagnostics.json`
 
-The session record tracks values such as:
-
-- `state`
-- `launchStrategy`
-- `specHash`
-- `bindAddr`
-- `port`
-- `userDataDir`
-- `extensionsDir`
-- `workspacePath`
-- `pid` for direct launches
-- `unitName` and `systemdScope` for systemd launches
-- timestamps and normalized failure details
-
-This disk-backed record is what allows the package to reuse, stop, restart, and inspect sessions across calls.
+## Preparation APIs
 
-## Reuse Model
+### `getCodeServerPreparationStatus(options?)`
 
-The package builds a normalized session spec from the effective launch plan plus lifecycle-relevant inputs such as:
+Checks whether the installed package looks ready to run and reports:
 
-- launch strategy
-- workspace path
-- trusted origins
-- env overrides
-- profile restore and persist configuration
-- systemd scope and unit naming
+- package root
+- support root
+- bootstrap script path
+- preparation state
+- issues
+- watchdog mode
 
-That normalized spec is hashed and stored. Reuse only happens when:
+### `ensureCodeServerPrepared(options?)`
 
-- the same `sessionKey` is used
-- the spec hash matches exactly
-- the backing process or unit still exists
-- the target port becomes ready again
+Runs the package-owned bootstrap script when the installation is repairable.
 
-If the hash changes, the package marks the old record stale, stops the old runtime when needed, and starts a fresh session.
+Use this explicitly when a host wants a preflight step. Otherwise the session manager runs it automatically.
 
 ## Launch Planning APIs
 
-The lower-level launch planning APIs remain available for callers that want policy ownership while still avoiding `code-server` package-layout details.
+The lower-level planning APIs still exist for hosts that want custom execution layers.
 
-### `resolveCodeServerInstallation(options?)`
+### `createCodeServerIntegrationPlan(options)`
 
-Returns installation metadata:
+This is the preferred lower-level planning API. It returns:
 
-- `packageRoot`
-- `packageJsonPath`
-- `entryPoint`
-- `entryRelativePath`
-- `entryKind`
-- `supportRoot`
-- `version`
+- final `command` and `args`
+- final `bindings`
+- `cwd` and `env`
+- preparation status
+- support-root bind suggestions
+- readable and writable path suggestions
+- host-visible and sandbox-visible path lists
+- translated path pairs
 
 ### `createCodeServerLaunchPlan(options)`
 
-Returns a structured launch plan with:
+Compatibility-friendly alias for callers that still want the previous naming. It now routes through the richer integration-plan path.
 
-- `command`
-- `args`
-- `cwd`
-- `env`
-- `entryKind`
-- `launchMode`
-- `installation`
-- `bindAddr`
-- `host`
-- `port`
-- `supportRoot`
-- `supportBindings`
-- `recommendedReadablePaths`
-- `recommendedWritablePaths`
-- `userDataDir`
-- `extensionsDir`
-- `workspacePath`
+The returned plan already includes final `bindings`, `recommendedReadablePaths`, `recommendedWritablePaths`, and `translatedPaths`, so a host does not need to rebuild support-tree mount decisions itself.
 
 ### `createCodeServerLaunchSpec(plan)`
 
-Converts the launch plan into an execution-oriented shape:
+Converts the plan into a smaller execution-oriented shape:
 
 - `command`
 - `args`
@@ -221,11 +198,9 @@ Converts the launch plan into an execution-oriented shape:
 - `readablePaths`
 - `writablePaths`
 
-This is useful when a host wants to feed the same plan into a container, custom sandbox, or generated unit file.
-
-## Direct Launch
+## Direct And Systemd Launching
 
-Use the built-in child-process helper when you want a plain process owned by the current Node.js runtime.
+### Direct
 
 ```ts
 import {
@@ -248,42 +223,111 @@ await waitForCodeServerReady({
 });
 ```
 
-The lifecycle manager uses this same lower-level path internally for `launchStrategy: "direct"`.
+### Session Diagnostics
 
-## Systemd Launch
+```ts
+const sessions = createCodeServerSessionManager();
 
-Linux systemd support is built into the same package and stays explicit.
+const started = await sessions.start({
+  sanitizer: {
+    pathPrefixes: ["/srv"],
+  },
+  sessionKey: "workspace-42",
+  stateRoot: "/srv/code-server-state",
+  trustedOrigins: ["https://app.example.com"],
+  workspacePath: "/srv/workspaces/demo",
+});
 
-Use `launchStrategy: "systemd"` only when you also provide:
+const diagnostics = await sessions.readDiagnostics({
+  sanitizer: {
+    pathPrefixes: ["/srv"],
+  },
+  sessionKey: "workspace-42",
+  stateRoot: "/srv/code-server-state",
+});
+
+console.log(started.status.lastStartSummary);
+console.log(diagnostics?.sanitized?.summary);
+```
 
-- `systemd.scope: "user"` or `"system"`
+### Systemd
 
-The package uses transient services through `systemd-run`, not scopes.
+Linux-first transient systemd support is built into the same package and stays explicit.
 
 Relevant APIs:
 
 - `launchCodeServerWithSystemd(options)`
+- `restartCodeServerSystemdUnit(options)`
 - `stopCodeServerSystemdUnit(options)`
 - `readCodeServerSystemdStatus(options)`
 - `readCodeServerSystemdJournal(options)`
+- `summarizeCodeServerSystemdJournal(options)`
+- `extractCodeServerSystemdFailure(options)`
 - `createCodeServerSystemdLaunchCommand(options)`
-- `buildSystemdPathProperties(spec)`
 
-The systemd translation layer derives:
+`systemd` launches require an explicit scope:
+
+- `scope: "user"`
+- `scope: "system"`
+
+There is no package default.
+
+```ts
+const sessions = createCodeServerSessionManager();
+
+const started = await sessions.start({
+  launchStrategy: "systemd",
+  sessionKey: "workspace-42",
+  stateRoot: "/srv/code-server-state",
+  systemd: {
+    scope: "user",
+  },
+  trustedOrigins: ["https://app.example.com"],
+  workspacePath: "/srv/workspaces/demo",
+});
+
+console.log(started.status.unitName);
+```
+
+## Diagnostics And Redaction
+
+### `collectCodeServerStartupDiagnostics(options)`
+
+Builds a structured diagnostic object with:
+
+- category
+- code
+- summary
+- machine-readable details
+- launch strategy
+- watchdog mode
+- stderr and stdout tails
+- systemd journal summary
+
+Supported normalized categories include:
+
+- `startup_timeout`
+- `process_exited_before_ready`
+- `systemd_launch_failed`
+- `systemd_unit_failed`
+- `entrypoint_resolution_failed`
+- `missing_runtime_dependency`
+- `preparation_failed`
+- `invalid_configuration`
+
+### `sanitizeCodeServerDiagnostics(diagnostics, options)`
+
+Supports:
 
-- `--unit`
-- `--working-directory`
-- `--setenv`
-- `BindPaths`
-- `BindReadOnlyPaths`
-- `ReadOnlyPaths`
-- `ReadWritePaths`
+- path-prefix redaction
+- exact-value redaction
+- a custom replacer hook
 
-That means host applications do not need to rebuild transient unit arguments from raw launch-plan data themselves.
+The package only sanitizes when a host asks for it.
 
-## Profile Restore And Persist
+## Profile Lifecycle
 
-Profile sync stays allowlist-based rather than copying the entire runtime tree.
+Profile sync stays allowlist-based instead of copying the whole runtime tree.
 
 Supported items:
 
@@ -293,56 +337,52 @@ Supported items:
 - `snippets`
 - `extensions`
 
-Lower-level helpers:
+Lower-level APIs:
 
 - `createCodeServerProfileSyncPlan(options)`
 - `syncCodeServerProfile(options)`
-- `resolveCodeServerProfilePathMap(overrides?)`
+- `readCodeServerProfileSnapshot(options)`
+- `readCodeServerProfileSignature(options)`
+- `persistCodeServerProfileIfChanged(options)`
 
-Lifecycle integration:
+Session-manager integration now handles:
 
-- restore before launch with `profile.restoreFrom`
-- persist after stop with `profile.persistTo`
-- skip missing or unreadable sources cleanly by default
-
-Example:
+- restore only when runtime profile data is missing or empty by default
+- persistence only when the allowlisted signature changed by default
+- optional extension snapshotting in the signature
 
 ```ts
+const sessions = createCodeServerSessionManager();
+
 await sessions.start({
   profile: {
-    items: ["settings.json", "keybindings.json", "extensions"],
-    persistTo: "/srv/profiles/demo",
-    restoreFrom: "/srv/profiles/demo",
+    persistTo: "/srv/code-server-profiles/workspace-42",
+    restoreFrom: "/srv/code-server-profiles/workspace-42",
+    snapshotExtensions: true,
   },
   sessionKey: "workspace-42",
   stateRoot: "/srv/code-server-state",
+  trustedOrigins: ["https://app.example.com"],
   workspacePath: "/srv/workspaces/demo",
 });
 ```
 
-## Readiness And Failure Handling
-
-### `waitForCodeServerReady(options)`
+## Proxy Helpers
 
-Waits for the TCP port to accept connections and can also:
+Generic proxy-facing helpers now include:
 
-- fail on startup timeout
-- fail on direct-process early exit
-- fail on a caller-provided failure probe
-
-The lifecycle manager builds on this and adds strategy-aware supervision:
+- `buildForwardedHeaders(options)`
+- `buildCodeServerWebSocketHeaders(options)`
+- `isCodeServerHtmlResponse(options)`
+- `classifyCodeServerProxyFailure(options)`
 
-- direct-process stdout and stderr tails
-- systemd state probing
-- systemd journal collection
-- normalized startup failure metadata
+These helpers stay framework-agnostic and do not add product-specific route rewriting.
 
 ## Structured Errors
 
-The package throws structured error classes so callers can log and branch on them reliably.
-
 Examples:
 
+- `CodeServerPreparationError`
 - `CodeServerInvalidConfigurationError`
 - `CodeServerInstallationResolutionError`
 - `CodeServerEntrypointResolutionError`
@@ -357,39 +397,43 @@ Examples:
 - `CodeServerSystemdStatusError`
 - `CodeServerSystemdJournalError`
 
-Use `normalizeCodeServerStartupFailure(error)` when you want one tagged object shape for logs or API responses.
-
-## Reverse Proxy Helpers
-
-The package also includes a few small generic embedding helpers:
+Use `normalizeCodeServerStartupFailure(error)` when you want one consistent structured startup-failure payload.
 
-- `buildForwardedHeaders(options)`
-- `normalizeTrustedOrigin(value)`
-- `isCodeServerHtmlResponse(options)`
+## Migration Note
 
-These helpers stay intentionally small. They do not add product-specific route rewriting.
+Existing host apps should delete generic glue for:
 
-## Logging
+- reading from `node_modules/code-server/...` directly
+- running `code-server` postinstall repair themselves
+- discovering support roots or remapping entrypoints manually
+- building support-tree read-only bind lists manually
+- translating host paths into sandbox-visible `code-server` paths
+- deduplicating concurrent starts for the same session key
+- comparing profile state before persisting
+- parsing raw startup output into user-facing summaries
+- building websocket proxy headers and classifying common upstream failures
 
-High-level APIs accept:
+Prefer:
 
-- `logger`
-- `loggerAdapter`
+- `createCodeServerSessionManager()`
+- `startCodeServerSession()`
 
-The package resolves those through `@trebired/logger-adapter`, matching the style used by other `@trebired/*` packages. `createCodeServerSessionManager()` also emits `logPackageInitialized()` on creation.
+Keep low-level APIs only when you truly need a custom execution layer.
 
-## `code-server`: Dependency vs Peer Dependency
+## Direct `code-server` Dependency
 
-Use `code-server` as a normal `dependency` when:
+None by default.
 
-- this package is part of an application deployment
-- you want the runtime to own the exact installed `code-server`
-- you want installation resolution to succeed without extra host setup
+Host applications only need a separate direct `code-server` dependency when they intentionally override resolution behavior, such as:
 
-Use `code-server` as a `peerDependency` in your own higher-level package when:
+- testing against a different installation root
+- pinning a different package copy outside `@trebired/code-server-kit`
+- using custom resolution during advanced development workflows
 
-- your package wraps `@trebired/code-server-kit`
-- the final host application should choose the `code-server` version
-- you want to avoid forcing duplicate `code-server` installs across wrappers
+## Intentionally Deferred
 
-`@trebired/code-server-kit` itself depends on `code-server` because the generic runtime layer needs a predictable package to resolve.
+- non-Linux lifecycle orchestration
+- container runtime wrappers
+- host-specific sandbox policy
+- Windows and macOS service-management behavior
+- a stronger watchdog strategy than preparation plus disabled-fallback classification, unless future `code-server` versions expose a cleaner supported switch

package/dist/diagnostics.d.ts

@@ -0,0 +1,6 @@
+import type { CodeServerSanitizedDiagnostics, CodeServerSanitizerOptions, CodeServerStartupDiagnostics, CollectCodeServerStartupDiagnosticsOptions, NormalizedCodeServerStartupFailure } from "./types.js";
+declare function collectCodeServerStartupDiagnostics(options?: CollectCodeServerStartupDiagnosticsOptions): CodeServerStartupDiagnostics;
+declare function sanitizeCodeServerDiagnostics(diagnostics: Pick<CodeServerStartupDiagnostics, "details" | "summary">, options: CodeServerSanitizerOptions): CodeServerSanitizedDiagnostics;
+declare function normalizeCodeServerStartupFailure(error: unknown, options?: Omit<CollectCodeServerStartupDiagnosticsOptions, "error">): NormalizedCodeServerStartupFailure;
+export { collectCodeServerStartupDiagnostics, normalizeCodeServerStartupFailure, sanitizeCodeServerDiagnostics, };
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAE5B,0CAA0C,EAC1C,kCAAkC,EACnC,MAAM,YAAY,CAAC;AAEpB,iBAAS,mCAAmC,CAAC,OAAO,GAAE,0CAA+C,GAAG,4BAA4B,CAgCnI;AAED,iBAAS,6BAA6B,CACpC,WAAW,EAAE,IAAI,CAAC,4BAA4B,EAAE,SAAS,GAAG,SAAS,CAAC,EACtE,OAAO,EAAE,0BAA0B,GAClC,8BAA8B,CAOhC;AAED,iBAAS,iCAAiC,CACxC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,IAAI,CAAC,0CAA0C,EAAE,OAAO,CAAM,GACtE,kCAAkC,CAYpC;AAoHD,OAAO,EACL,mCAAmC,EACnC,iCAAiC,EACjC,6BAA6B,GAC9B,CAAC"}