@trebired/code-server-kit 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 - nothing yet
 
+## 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
+- add session lifecycle APIs for start, stop, restart, status, diagnostics, and session-manager creation
+- add Linux-first transient systemd helpers and launch-command builders
+- add disk-backed session metadata, reuse checks, profile restore and persist hooks, and richer startup diagnostics
+- add `@trebired/logger-adapter` support across the higher-level APIs
+
 ## 0.2.0
 
 - add `createCodeServerLaunchPlan()` as the main higher-level launch planning API

package/README.md

@@ -1,186 +1,205 @@
 # @trebired/code-server-kit
 
-Framework-agnostic `code-server` integration helpers for Node.js applications.
+Framework-agnostic `code-server` integration layer for Node.js applications.
 
-`@trebired/code-server-kit` gives host applications a typed, generic layer for resolving an installed `code-server`, building a complete launch plan, waiting for readiness, syncing selected profile data, and preparing the result for direct processes, systemd units, containers, or custom sandboxes.
+`@trebired/code-server-kit` is the generic Trebired package for owning the real `code-server` integration lifecycle on Linux-first hosts:
 
-The package stays in one lane:
+- 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
 
-- resolve the installed `code-server` package root and launch entrypoint
-- describe the final launch command, args, cwd, env, and path-access suggestions
-- expose structured errors that host apps can log and branch on
-- optionally spawn the process and wait for readiness
-- sync allowlisted profile data without copying a whole runtime tree
-- help reverse-proxy integrations with trusted-origin and forwarded-header helpers
-
-It does not try to be a `code-server` fork, a sandbox manager, a container runtime, or a product layer with app-specific routes and filesystem rules.
+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
 ```
 
-## Quick Start
+`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.
+
+## Preferred Flow
+
+The preferred host integration flow is now:
+
+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 {
-  createCodeServerLaunchPlan,
-  launchCodeServerProcess,
-  waitForCodeServerReady,
+  createCodeServerSessionManager,
 } from "@trebired/code-server-kit";
 
-const plan = await createCodeServerLaunchPlan({
-  dataRoot: "/srv/code-server/session-42",
-  host: "127.0.0.1",
-  port: 8080,
+const sessions = createCodeServerSessionManager({
+  logger: console,
+});
+
+const started = await sessions.start({
+  sessionKey: "workspace-42",
+  stateRoot: "/srv/code-server-state",
   trustedOrigins: [
     "https://app.example.com",
   ],
   workspacePath: "/srv/workspaces/demo",
 });
 
-const handle = await launchCodeServerProcess({
-  plan,
-  stdout(text) {
-    process.stdout.write(text);
-  },
-  stderr(text) {
-    process.stderr.write(text);
-  },
+console.log(started.status.state, started.status.port);
+
+const status = await sessions.getStatus({
+  sessionKey: "workspace-42",
+  stateRoot: "/srv/code-server-state",
 });
 
-await waitForCodeServerReady({
-  host: plan.host,
-  port: plan.port,
-  process: handle,
-  timeoutMs: 30_000,
+console.log(status?.ready);
+
+await sessions.stop({
+  sessionKey: "workspace-42",
+  stateRoot: "/srv/code-server-state",
 });
 ```
 
-## Why The Launch Plan Exists
+## What The Package Owns
 
-Most host apps do not want to know where `code-server` put its real entry file, when to call `node <entry.js>` versus a direct executable, which package directories should be mounted read-only, or which runtime paths must stay writable.
+High-level APIs now own generic mechanics that host apps previously had to rebuild:
 
-`createCodeServerLaunchPlan()` moves that generic integration work into one reusable contract so host apps can focus on policy instead:
+- 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
 
-- what workspace should be opened
-- which paths should actually be writable in a sandbox
-- how processes are supervised
-- which users, tokens, or routes exist in the host product
+Host applications mostly provide:
 
-## Main Planning API
+- `sessionKey`
+- `stateRoot`
+- `workspacePath`
+- `trustedOrigins`
+- `launchStrategy`
+- systemd `scope` when using systemd
+- optional profile and sanitization policy
+- optional logging
 
-### `createCodeServerLaunchPlan(options)`
+## Main High-Level APIs
 
-This is the main higher-level API. It returns a structured `CodeServerLaunchPlan` with:
+### `createCodeServerSessionManager(options?)`
 
-- `command`
-- `args`
-- `cwd`
-- `env`
-- `entryKind`
-- `launchMode`
-- `installation`
-- `userDataDir`
-- `extensionsDir`
-- `supportRoot`
-- `supportBindings`
-- `recommendedReadablePaths`
-- `recommendedWritablePaths`
-- `bindAddr`
-- `host`
-- `port`
-- `trustedOrigins`
-- `workspacePath`
+Creates the main lifecycle object.
 
-If you pass `dataRoot`, the package derives:
+Manager methods:
 
-- `${dataRoot}/user-data`
-- `${dataRoot}/extensions`
+- `start(options)`
+- `stop(options)`
+- `restart(options)`
+- `getStatus(options)`
+- `readDiagnostics(options)`
 
-If you omit `port` or pass `0`, the package allocates a free TCP port first.
+### `startCodeServerSession(options)`
 
-Example:
+One-shot helper around the session manager.
 
-```ts
-import { createCodeServerLaunchPlan } from "@trebired/code-server-kit";
+Defaults:
 
-const plan = await createCodeServerLaunchPlan({
-  dataRoot: "/srv/code-server/session-42",
-  host: "127.0.0.1",
-  port: 0,
-  trustedOrigins: [
-    "https://app.example.com",
-    "https://admin.example.com",
-  ],
-  workspacePath: "/srv/workspaces/demo",
-});
-```
+- `launchStrategy` defaults to `"direct"`
+- 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"`
 
-### `resolveCodeServerInstallation(options?)`
+### `getCodeServerSessionStatus(options)`
 
-Use this lower-level helper when you only need installation metadata:
+Returns a refreshed status object with:
 
-- `packageRoot`
-- `packageJsonPath`
-- `entryPoint`
-- `entryRelativePath`
-- `entryKind`
-- `supportRoot`
-- `version`
+- `state`
+- `health`
+- `ready`
+- `preparation`
+- `watchdogMode`
+- `lastStartSummary`
+- `sanitizedDiagnostics`
 
-### `createCodeServerLaunch(options)`
+### `readCodeServerSessionDiagnostics(options)`
 
-This remains available as a compatibility-friendly alias for `createCodeServerLaunchPlan()`.
+Reads the persisted diagnostics snapshot under:
 
-## Launch Specs And Sandbox Helpers
+- `<stateRoot>/sessions/<safe-session-key>/session.json`
+- `<stateRoot>/sessions/<safe-session-key>/diagnostics.json`
 
-### `createCodeServerLaunchSpec(plan)`
+## Preparation APIs
 
-Converts a launch plan into a smaller execution-oriented shape:
+### `getCodeServerPreparationStatus(options?)`
 
-- `command`
-- `args`
-- `cwd`
-- `env`
-- `readablePaths`
-- `writablePaths`
-- `bindings`
+Checks whether the installed package looks ready to run and reports:
+
+- package root
+- support root
+- bootstrap script path
+- preparation state
+- issues
+- watchdog mode
+
+### `ensureCodeServerPrepared(options?)`
+
+Runs the package-owned bootstrap script when the installation is repairable.
 
-This is useful when a caller wants to feed the launch plan into:
+Use this explicitly when a host wants a preflight step. Otherwise the session manager runs it automatically.
 
-- a direct child-process launch
-- a systemd unit generator
-- a container wrapper
-- a custom sandbox layer
+## Launch Planning APIs
 
-### `formatCodeServerCommand(planOrSpec)`
+The lower-level planning APIs still exist for hosts that want custom execution layers.
 
-Formats the command and arg vector as one safely escaped string for logs, debug output, shell transcripts, or generated unit files.
+### `createCodeServerIntegrationPlan(options)`
 
-### `normalizeCodeServerStartupFailure(error)`
+This is the preferred lower-level planning API. It returns:
 
-Converts package-specific and generic thrown values into one consistent startup-failure shape with:
+- final `command` and `args`
+- `cwd` and `env`
+- preparation status
+- support-root bind suggestions
+- readable and writable path suggestions
+- host-visible and sandbox-visible path lists
+- translated path pairs
 
-- `name`
-- `message`
-- `code`
-- `details`
-- `isCodeServerKitError`
+### `createCodeServerLaunchPlan(options)`
+
+Compatibility-friendly alias for callers that still want the previous naming. It now routes through the richer integration-plan path.
+
+### `createCodeServerLaunchSpec(plan)`
+
+Converts the plan into a smaller execution-oriented shape:
 
-## Launching Strategies
+- `command`
+- `args`
+- `cwd`
+- `env`
+- `bindings`
+- `readablePaths`
+- `writablePaths`
 
-### Direct Child Process
+## Direct And Systemd Launching
 
-Use the built-in launcher when you want a plain host-owned child process:
+### Direct
 
 ```ts
 import {
   createCodeServerLaunchPlan,
   launchCodeServerProcess,
+  waitForCodeServerReady,
 } from "@trebired/code-server-kit";
 
 const plan = await createCodeServerLaunchPlan({
@@ -189,66 +208,77 @@ const plan = await createCodeServerLaunchPlan({
 });
 
 const handle = await launchCodeServerProcess({ plan });
+
+await waitForCodeServerReady({
+  host: plan.host,
+  port: plan.port,
+  process: handle,
+});
 ```
 
 ### Systemd
 
-Use `createCodeServerLaunchPlan()` or `createCodeServerLaunchSpec()` to generate:
+Linux-first transient systemd support is built into the same package and stays explicit.
 
-- `ExecStart` from `command` plus `args`
-- `WorkingDirectory` from `cwd`
-- `Environment` lines from `env`
-- read and write path policy from `bindings`, `readablePaths`, and `writablePaths`
+Relevant APIs:
 
-### Containers
+- `launchCodeServerWithSystemd(options)`
+- `restartCodeServerSystemdUnit(options)`
+- `stopCodeServerSystemdUnit(options)`
+- `readCodeServerSystemdStatus(options)`
+- `readCodeServerSystemdJournal(options)`
+- `summarizeCodeServerSystemdJournal(options)`
+- `extractCodeServerSystemdFailure(options)`
+- `createCodeServerSystemdLaunchCommand(options)`
 
-Use the launch plan to decide:
+`systemd` launches require an explicit scope:
 
-- which package and support paths should be mounted read-only
-- which runtime paths should be mounted writable
-- the final command and arg vector inside the container
+- `scope: "user"`
+- `scope: "system"`
 
-The package does not impose a container layout. It only returns generic path suggestions.
+There is no package default.
 
-### Custom Sandboxes
+## Diagnostics And Redaction
 
-Use `supportBindings`, `recommendedReadablePaths`, and `recommendedWritablePaths` as generic inputs to your own sandbox policy. Host apps can tighten or expand those lists without re-deriving them from package internals.
+### `collectCodeServerStartupDiagnostics(options)`
 
-## Readiness Helpers
+Builds a structured diagnostic object with:
 
-### `waitForCodeServerReady(options)`
+- category
+- code
+- summary
+- machine-readable details
+- launch strategy
+- watchdog mode
+- stderr and stdout tails
+- systemd journal summary
 
-Waits for the target TCP port to accept connections and can also:
+Supported normalized categories include:
 
-- fail on startup timeout
-- fail early if a child process exits first
-- run a caller-provided `failureProbe`
+- `startup_timeout`
+- `process_exited_before_ready`
+- `systemd_launch_failed`
+- `systemd_unit_failed`
+- `entrypoint_resolution_failed`
+- `missing_runtime_dependency`
+- `preparation_failed`
+- `invalid_configuration`
 
-The readiness helper throws structured errors instead of returning vague booleans.
+### `sanitizeCodeServerDiagnostics(diagnostics, options)`
 
-Example:
+Supports:
 
-```ts
-await waitForCodeServerReady({
-  host: plan.host,
-  port: plan.port,
-  process: handle,
-  failureProbe({ elapsedMs }) {
-    if (elapsedMs > 10_000) {
-      return {
-        message: "startup looked stalled",
-      };
-    }
-    return null;
-  },
-});
-```
+- path-prefix redaction
+- exact-value redaction
+- a custom replacer hook
 
-## Profile Sync Helpers
+The package only sanitizes when a host asks for it.
 
-The package now includes generic profile sync helpers built around an allowlist model.
+## Profile Lifecycle
 
-Supported profile items:
+Profile sync stays allowlist-based instead of copying the whole runtime tree.
+
+Supported items:
 
 - `settings.json`
 - `extensions.json`
@@ -256,89 +286,77 @@ Supported profile items:
 - `snippets`
 - `extensions`
 
-### `createCodeServerProfileSyncPlan(options)`
-
-Builds a sync plan between two profile roots without copying anything yet.
-
-### `syncCodeServerProfile(options)`
+Lower-level APIs:
 
-Copies only the allowlisted profile items. By default it skips missing or unreadable sources cleanly instead of assuming full access to every runtime-owned path.
+- `createCodeServerProfileSyncPlan(options)`
+- `syncCodeServerProfile(options)`
+- `readCodeServerProfileSnapshot(options)`
+- `readCodeServerProfileSignature(options)`
+- `persistCodeServerProfileIfChanged(options)`
 
-Example:
-
-```ts
-import { syncCodeServerProfile } from "@trebired/code-server-kit";
-
-const result = await syncCodeServerProfile({
-  sourceDir: "/srv/persisted-profile",
-  targetDir: "/srv/runtime-profile",
-  items: ["settings.json", "snippets", "extensions"],
-});
-
-console.log(result.copied.length, result.skipped.length);
-```
+Session-manager integration now handles:
 
-Default relative paths are also exported through `DEFAULT_CODE_SERVER_PROFILE_PATHS`, and callers can override them when needed through `pathMap`.
+- 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
 
-## Reverse Proxy Helpers
+## Proxy Helpers
 
-### `normalizeTrustedOrigins(origins)`
+Generic proxy-facing helpers now include:
 
-Normalizes absolute origins for launch planning and rejects invalid values clearly.
+- `buildForwardedHeaders(options)`
+- `buildCodeServerWebSocketHeaders(options)`
+- `isCodeServerHtmlResponse(options)`
+- `classifyCodeServerProxyFailure(options)`
 
-### `normalizeTrustedOrigin(origin)`
-
-Normalizes one origin value.
-
-### `buildForwardedHeaders(options)`
-
-Builds a small forwarded-header record for reverse-proxy embedding.
-
-### `isCodeServerHtmlResponse(options)`
-
-Returns `true` when a response looks like HTML that a host app may want to transform before returning it to a browser.
-
-This helper is intentionally narrow. It does not rewrite routes or inject product-specific markup.
+These helpers stay framework-agnostic and do not add product-specific route rewriting.
 
 ## Structured Errors
 
-The package exposes structured error classes so host apps can log clearly and branch reliably:
+Examples:
 
+- `CodeServerPreparationError`
+- `CodeServerInvalidConfigurationError`
 - `CodeServerInstallationResolutionError`
 - `CodeServerEntrypointResolutionError`
 - `CodeServerLaunchPlanningError`
-- `CodeServerInvalidConfigurationError`
 - `CodeServerPortAllocationError`
-- `CodeServerProcessExitedBeforeReadyError`
-- `CodeServerStartupProbeError`
 - `CodeServerStartupTimeoutError`
+- `CodeServerProcessExitedBeforeReadyError`
+- `CodeServerSessionLifecycleError`
+- `CodeServerSessionReuseConflictError`
+- `CodeServerSystemdLaunchError`
+- `CodeServerSystemdCollisionError`
+- `CodeServerSystemdStatusError`
+- `CodeServerSystemdJournalError`
+
+Use `normalizeCodeServerStartupFailure(error)` when you want one consistent structured startup-failure payload.
 
-The earlier compatibility exports are still available:
+## Migration Note
 
-- `CodeServerPackageResolutionError`
-- `CodeServerBinaryNotFoundError`
+Existing host apps should delete generic glue for:
 
-## Public Surface
+- 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
 
-The current API is centered around these exports:
+Prefer:
 
-- `resolveCodeServerInstallation()`
-- `createCodeServerLaunchPlan()`
-- `createCodeServerLaunch()`
-- `createCodeServerLaunchSpec()`
-- `launchCodeServerProcess()`
-- `waitForCodeServerReady()`
-- `createCodeServerProfileSyncPlan()`
-- `syncCodeServerProfile()`
-- `buildForwardedHeaders()`
-- `normalizeTrustedOrigins()`
-- `normalizeTrustedOrigin()`
-- `isCodeServerHtmlResponse()`
-- `formatCodeServerCommand()`
-- `normalizeCodeServerStartupFailure()`
+- `createCodeServerSessionManager()`
+- `startCodeServerSession()`
 
-## Dependency vs Peer Dependency for `code-server`
+Keep low-level APIs only when you truly need a custom execution layer.
 
-For an application, prefer a regular `dependency` on `code-server` when you want one installed runtime and want `@trebired/code-server-kit` to resolve the same package reliably every time.
+## Intentionally Deferred
 
-For a wrapper library on top of this package, prefer a `peerDependency` on `code-server` when the host application must choose the exact `code-server` version and install location itself. In that setup, document that `code-server` must still be resolvable from the host application's dependency tree, and pass `resolveFrom` when you need to anchor resolution to the host side explicitly.
+- 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"}