@trebired/code-server-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+- nothing yet
+
+## 0.2.0
+
+- add `createCodeServerLaunchPlan()` as the main higher-level launch planning API
+- add generic launch spec, command formatting, and startup failure normalization helpers
+- add readiness probe support and broader structured error coverage
+- add generic allowlisted profile sync helpers for `code-server` user data and extensions
+- add reverse-proxy helpers for forwarded headers, trusted origins, and HTML response detection
+
 ## 0.1.0
 
 - Initial release

package/README.md

@@ -1,16 +1,17 @@
 # @trebired/code-server-kit
 
-Framework-agnostic `code-server` launch planning for Node.js applications.
+Framework-agnostic `code-server` integration helpers for Node.js applications.
 
-`@trebired/code-server-kit` gives your app a small, typed layer for finding an installed `code-server`, building a stable launch command, waiting for readiness, and optionally spawning the process without leaking `code-server` package layout details into product code.
+`@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.
 
 The package stays in one lane:
 
 - resolve the installed `code-server` package root and launch entrypoint
-- build standard `code-server` CLI args for host-managed sessions
-- expose the launch command and args for your own sandbox or supervisor
-- optionally spawn the process and capture stdout and stderr
-- wait for the TCP port to become ready with timeout and early-exit handling
+- 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.
 
@@ -26,18 +27,12 @@ npm install @trebired/code-server-kit code-server
 
 ```ts
 import {
-  createCodeServerLaunch,
+  createCodeServerLaunchPlan,
   launchCodeServerProcess,
-  resolveCodeServerInstallation,
   waitForCodeServerReady,
 } from "@trebired/code-server-kit";
 
-const installation = resolveCodeServerInstallation({
-  resolveFrom: process.cwd(),
-});
-
-const launch = await createCodeServerLaunch({
-  installation,
+const plan = await createCodeServerLaunchPlan({
   dataRoot: "/srv/code-server/session-42",
   host: "127.0.0.1",
   port: 8080,
@@ -47,8 +42,8 @@ const launch = await createCodeServerLaunch({
   workspacePath: "/srv/workspaces/demo",
 });
 
-const processHandle = await launchCodeServerProcess({
-  plan: launch,
+const handle = await launchCodeServerProcess({
+  plan,
   stdout(text) {
     process.stdout.write(text);
   },
@@ -58,39 +53,47 @@ const processHandle = await launchCodeServerProcess({
 });
 
 await waitForCodeServerReady({
-  host: launch.host,
-  port: launch.port,
-  process: processHandle,
+  host: plan.host,
+  port: plan.port,
+  process: handle,
   timeoutMs: 30_000,
 });
 ```
 
-## Public API
+## Why The Launch Plan Exists
 
-### `resolveCodeServerInstallation(options?)`
+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.
 
-Resolves the installed `code-server` package from a caller-controlled starting path and returns:
+`createCodeServerLaunchPlan()` moves that generic integration work into one reusable contract so host apps can focus on policy instead:
 
-- `packageRoot`
-- `packageJsonPath`
-- `entryPoint`
-- `entryKind`
-- `supportRoot`
-- `version`
+- 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
 
-### `createCodeServerLaunch(options)`
+## Main Planning API
 
-Builds a stable launch plan and returns:
+### `createCodeServerLaunchPlan(options)`
+
+This is the main higher-level API. It returns a structured `CodeServerLaunchPlan` with:
 
 - `command`
 - `args`
-- `codeServerPackageRoot`
-- `supportRoot`
+- `cwd`
+- `env`
+- `entryKind`
+- `launchMode`
+- `installation`
 - `userDataDir`
 - `extensionsDir`
+- `supportRoot`
+- `supportBindings`
+- `recommendedReadablePaths`
+- `recommendedWritablePaths`
 - `bindAddr`
 - `host`
 - `port`
+- `trustedOrigins`
 - `workspacePath`
 
 If you pass `dataRoot`, the package derives:
@@ -100,60 +103,242 @@ If you pass `dataRoot`, the package derives:
 
 If you omit `port` or pass `0`, the package allocates a free TCP port first.
 
+Example:
+
+```ts
+import { createCodeServerLaunchPlan } from "@trebired/code-server-kit";
+
+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",
+});
+```
+
+### `resolveCodeServerInstallation(options?)`
+
+Use this lower-level helper when you only need installation metadata:
+
+- `packageRoot`
+- `packageJsonPath`
+- `entryPoint`
+- `entryRelativePath`
+- `entryKind`
+- `supportRoot`
+- `version`
+
+### `createCodeServerLaunch(options)`
+
+This remains available as a compatibility-friendly alias for `createCodeServerLaunchPlan()`.
+
+## Launch Specs And Sandbox Helpers
+
+### `createCodeServerLaunchSpec(plan)`
+
+Converts a launch plan into a smaller execution-oriented shape:
+
+- `command`
+- `args`
+- `cwd`
+- `env`
+- `readablePaths`
+- `writablePaths`
+- `bindings`
+
+This is useful when a caller wants to feed the launch plan into:
+
+- a direct child-process launch
+- a systemd unit generator
+- a container wrapper
+- a custom sandbox layer
+
+### `formatCodeServerCommand(planOrSpec)`
+
+Formats the command and arg vector as one safely escaped string for logs, debug output, shell transcripts, or generated unit files.
+
+### `normalizeCodeServerStartupFailure(error)`
+
+Converts package-specific and generic thrown values into one consistent startup-failure shape with:
+
+- `name`
+- `message`
+- `code`
+- `details`
+- `isCodeServerKitError`
+
+## Launching Strategies
+
+### Direct Child Process
+
+Use the built-in launcher when you want a plain host-owned child process:
+
+```ts
+import {
+  createCodeServerLaunchPlan,
+  launchCodeServerProcess,
+} from "@trebired/code-server-kit";
+
+const plan = await createCodeServerLaunchPlan({
+  dataRoot: "/srv/code-server/session-42",
+  workspacePath: "/srv/workspaces/demo",
+});
+
+const handle = await launchCodeServerProcess({ plan });
+```
+
+### Systemd
+
+Use `createCodeServerLaunchPlan()` or `createCodeServerLaunchSpec()` to generate:
+
+- `ExecStart` from `command` plus `args`
+- `WorkingDirectory` from `cwd`
+- `Environment` lines from `env`
+- read and write path policy from `bindings`, `readablePaths`, and `writablePaths`
+
+### Containers
+
+Use the launch plan to decide:
+
+- 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
+
+The package does not impose a container layout. It only returns generic path suggestions.
+
+### Custom Sandboxes
+
+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.
+
+## Readiness Helpers
+
 ### `waitForCodeServerReady(options)`
 
-Polls the target TCP port until it accepts connections or fails with:
+Waits for the target TCP port to accept connections and can also:
 
-- `CodeServerProcessExitedBeforeReadyError`
-- `CodeServerStartupTimeoutError`
+- fail on startup timeout
+- fail early if a child process exits first
+- run a caller-provided `failureProbe`
 
-### `launchCodeServerProcess(options)`
+The readiness helper throws structured errors instead of returning vague booleans.
 
-Starts the resolved command directly with `stdout` and `stderr` hooks and returns a typed handle with:
+Example:
 
-- `child`
-- `pid`
-- `exit`
-- `kill()`
-- `getStdout()`
-- `getStderr()`
+```ts
+await waitForCodeServerReady({
+  host: plan.host,
+  port: plan.port,
+  process: handle,
+  failureProbe({ elapsedMs }) {
+    if (elapsedMs > 10_000) {
+      return {
+        message: "startup looked stalled",
+      };
+    }
+    return null;
+  },
+});
+```
 
-## Launch Modes
+## Profile Sync Helpers
 
-`createCodeServerLaunch()` supports two concrete launch modes:
+The package now includes generic profile sync helpers built around an allowlist model.
 
-- `node`, which runs `node <entrypoint> ...`
-- `direct`, which runs the resolved entrypoint directly when it is executable
+Supported profile items:
 
-`auto` is the default. It prefers `node` for JS entry files and `direct` for non-JS executables.
+- `settings.json`
+- `extensions.json`
+- `keybindings.json`
+- `snippets`
+- `extensions`
 
-## Standard CLI Args
+### `createCodeServerProfileSyncPlan(options)`
 
-The launch plan always includes:
+Builds a sync plan between two profile roots without copying anything yet.
 
-- `--auth none`
-- `--bind-addr`
-- `--disable-telemetry`
-- `--disable-update-check`
-- `--disable-workspace-trust`
-- `--disable-getting-started-override`
-- `--user-data-dir`
-- `--extensions-dir`
+### `syncCodeServerProfile(options)`
 
-Trusted origins are appended with repeated `--trusted-origins` flags, and `workspacePath` is appended as the positional workspace/folder target when provided.
+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.
 
-## Dependency vs Peer Dependency for `code-server`
+Example:
 
-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.
+```ts
+import { syncCodeServerProfile } from "@trebired/code-server-kit";
 
-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.
+const result = await syncCodeServerProfile({
+  sourceDir: "/srv/persisted-profile",
+  targetDir: "/srv/runtime-profile",
+  items: ["settings.json", "snippets", "extensions"],
+});
 
-## Error Types
+console.log(result.copied.length, result.skipped.length);
+```
 
-The package exposes structured errors for the failure modes that usually matter in integration code:
+Default relative paths are also exported through `DEFAULT_CODE_SERVER_PROFILE_PATHS`, and callers can override them when needed through `pathMap`.
 
-- `CodeServerBinaryNotFoundError`
-- `CodeServerPackageResolutionError`
+## Reverse Proxy Helpers
+
+### `normalizeTrustedOrigins(origins)`
+
+Normalizes absolute origins for launch planning and rejects invalid values clearly.
+
+### `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.
+
+## Structured Errors
+
+The package exposes structured error classes so host apps can log clearly and branch reliably:
+
+- `CodeServerInstallationResolutionError`
+- `CodeServerEntrypointResolutionError`
+- `CodeServerLaunchPlanningError`
+- `CodeServerInvalidConfigurationError`
 - `CodeServerPortAllocationError`
 - `CodeServerProcessExitedBeforeReadyError`
+- `CodeServerStartupProbeError`
 - `CodeServerStartupTimeoutError`
+
+The earlier compatibility exports are still available:
+
+- `CodeServerPackageResolutionError`
+- `CodeServerBinaryNotFoundError`
+
+## Public Surface
+
+The current API is centered around these exports:
+
+- `resolveCodeServerInstallation()`
+- `createCodeServerLaunchPlan()`
+- `createCodeServerLaunch()`
+- `createCodeServerLaunchSpec()`
+- `launchCodeServerProcess()`
+- `waitForCodeServerReady()`
+- `createCodeServerProfileSyncPlan()`
+- `syncCodeServerProfile()`
+- `buildForwardedHeaders()`
+- `normalizeTrustedOrigins()`
+- `normalizeTrustedOrigin()`
+- `isCodeServerHtmlResponse()`
+- `formatCodeServerCommand()`
+- `normalizeCodeServerStartupFailure()`
+
+## Dependency vs Peer Dependency for `code-server`
+
+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.
+
+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.

package/dist/errors.d.ts

@@ -1,13 +1,19 @@
-type CodeServerKitErrorCode = "binary_not_found" | "package_resolution_failed" | "port_allocation_failed" | "process_exited_before_ready" | "startup_timeout";
+type CodeServerKitErrorCode = "entrypoint_resolution_failed" | "installation_resolution_failed" | "invalid_configuration" | "launch_planning_failed" | "port_allocation_failed" | "process_exited_before_ready" | "startup_probe_failed" | "startup_timeout";
 declare class CodeServerKitError extends Error {
     code: CodeServerKitErrorCode | string;
     details: Record<string, unknown>;
     constructor(code: CodeServerKitErrorCode | string, message: string, details?: Record<string, unknown>);
 }
-declare class CodeServerBinaryNotFoundError extends CodeServerKitError {
+declare class CodeServerInstallationResolutionError extends CodeServerKitError {
     constructor(message: string, details?: Record<string, unknown>);
 }
-declare class CodeServerPackageResolutionError extends CodeServerKitError {
+declare class CodeServerEntrypointResolutionError extends CodeServerKitError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class CodeServerLaunchPlanningError extends CodeServerKitError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class CodeServerInvalidConfigurationError extends CodeServerKitError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 declare class CodeServerPortAllocationError extends CodeServerKitError {
@@ -19,7 +25,16 @@ declare class CodeServerProcessExitedBeforeReadyError extends CodeServerKitError
 declare class CodeServerStartupTimeoutError extends CodeServerKitError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+declare class CodeServerStartupProbeError extends CodeServerKitError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class CodeServerPackageResolutionError extends CodeServerInstallationResolutionError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class CodeServerBinaryNotFoundError extends CodeServerEntrypointResolutionError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
 declare function isCodeServerKitError(value: unknown): value is CodeServerKitError;
-export { CodeServerBinaryNotFoundError, CodeServerKitError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupTimeoutError, isCodeServerKitError, };
+export { CodeServerBinaryNotFoundError, CodeServerEntrypointResolutionError, CodeServerInstallationResolutionError, CodeServerInvalidConfigurationError, CodeServerKitError, CodeServerLaunchPlanningError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupProbeError, CodeServerStartupTimeoutError, isCodeServerKitError, };
 export type { CodeServerKitErrorCode };
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,KAAK,sBAAsB,GACvB,kBAAkB,GAClB,2BAA2B,GAC3B,wBAAwB,GACxB,6BAA6B,GAC7B,iBAAiB,CAAC;AAEtB,cAAM,kBAAmB,SAAQ,KAAK;IACpC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAErB,IAAI,EAAE,sBAAsB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAM1G;AAED,cAAM,6BAA8B,SAAQ,kBAAkB;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,gCAAiC,SAAQ,kBAAkB;gBACnD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,6BAA8B,SAAQ,kBAAkB;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,uCAAwC,SAAQ,kBAAkB;gBAC1D,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,6BAA8B,SAAQ,kBAAkB;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,iBAAS,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEzE;AAED,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,gCAAgC,EAChC,6BAA6B,EAC7B,uCAAuC,EACvC,6BAA6B,EAC7B,oBAAoB,GACrB,CAAC;AACF,YAAY,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,KAAK,sBAAsB,GACvB,8BAA8B,GAC9B,gCAAgC,GAChC,uBAAuB,GACvB,wBAAwB,GACxB,wBAAwB,GACxB,6BAA6B,GAC7B,sBAAsB,GACtB,iBAAiB,CAAC;AAEtB,cAAM,kBAAmB,SAAQ,KAAK;IACpC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAErB,IAAI,EAAE,sBAAsB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAM1G;AAED,cAAM,qCAAsC,SAAQ,kBAAkB;gBACxD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,mCAAoC,SAAQ,kBAAkB;gBACtD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,6BAA8B,SAAQ,kBAAkB;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,mCAAoC,SAAQ,kBAAkB;gBACtD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,6BAA8B,SAAQ,kBAAkB;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,uCAAwC,SAAQ,kBAAkB;gBAC1D,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,6BAA8B,SAAQ,kBAAkB;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,2BAA4B,SAAQ,kBAAkB;gBAC9C,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,gCAAiC,SAAQ,qCAAqC;gBACtE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,cAAM,6BAA8B,SAAQ,mCAAmC;gBACjE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAInE;AAED,iBAAS,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEzE;AAED,OAAO,EACL,6BAA6B,EAC7B,mCAAmC,EACnC,qCAAqC,EACrC,mCAAmC,EACnC,kBAAkB,EAClB,6BAA6B,EAC7B,gCAAgC,EAChC,6BAA6B,EAC7B,uCAAuC,EACvC,2BAA2B,EAC3B,6BAA6B,EAC7B,oBAAoB,GACrB,CAAC;AACF,YAAY,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/errors.js

@@ -6,16 +6,28 @@ class CodeServerKitError extends Error {
         this.details = details;
     }
 }
-class CodeServerBinaryNotFoundError extends CodeServerKitError {
+class CodeServerInstallationResolutionError extends CodeServerKitError {
     constructor(message, details = {}) {
-        super("binary_not_found", message, details);
-        this.name = "CodeServerBinaryNotFoundError";
+        super("installation_resolution_failed", message, details);
+        this.name = "CodeServerInstallationResolutionError";
     }
 }
-class CodeServerPackageResolutionError extends CodeServerKitError {
+class CodeServerEntrypointResolutionError extends CodeServerKitError {
     constructor(message, details = {}) {
-        super("package_resolution_failed", message, details);
-        this.name = "CodeServerPackageResolutionError";
+        super("entrypoint_resolution_failed", message, details);
+        this.name = "CodeServerEntrypointResolutionError";
+    }
+}
+class CodeServerLaunchPlanningError extends CodeServerKitError {
+    constructor(message, details = {}) {
+        super("launch_planning_failed", message, details);
+        this.name = "CodeServerLaunchPlanningError";
+    }
+}
+class CodeServerInvalidConfigurationError extends CodeServerKitError {
+    constructor(message, details = {}) {
+        super("invalid_configuration", message, details);
+        this.name = "CodeServerInvalidConfigurationError";
     }
 }
 class CodeServerPortAllocationError extends CodeServerKitError {
@@ -36,8 +48,26 @@ class CodeServerStartupTimeoutError extends CodeServerKitError {
         this.name = "CodeServerStartupTimeoutError";
     }
 }
+class CodeServerStartupProbeError extends CodeServerKitError {
+    constructor(message, details = {}) {
+        super("startup_probe_failed", message, details);
+        this.name = "CodeServerStartupProbeError";
+    }
+}
+class CodeServerPackageResolutionError extends CodeServerInstallationResolutionError {
+    constructor(message, details = {}) {
+        super(message, details);
+        this.name = "CodeServerPackageResolutionError";
+    }
+}
+class CodeServerBinaryNotFoundError extends CodeServerEntrypointResolutionError {
+    constructor(message, details = {}) {
+        super(message, details);
+        this.name = "CodeServerBinaryNotFoundError";
+    }
+}
 function isCodeServerKitError(value) {
     return value instanceof CodeServerKitError;
 }
-export { CodeServerBinaryNotFoundError, CodeServerKitError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupTimeoutError, isCodeServerKitError, };
+export { CodeServerBinaryNotFoundError, CodeServerEntrypointResolutionError, CodeServerInstallationResolutionError, CodeServerInvalidConfigurationError, CodeServerKitError, CodeServerLaunchPlanningError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupProbeError, CodeServerStartupTimeoutError, isCodeServerKitError, };
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA,MAAM,kBAAmB,SAAQ,KAAK;IAIpC,YAAY,IAAqC,EAAE,OAAe,EAAE,UAAmC,EAAE;QACvG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,6BAA8B,SAAQ,kBAAkB;IAC5D,YAAY,OAAe,EAAE,UAAmC,EAAE;QAChE,KAAK,CAAC,kBAAkB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,gCAAiC,SAAQ,kBAAkB;IAC/D,YAAY,OAAe,EAAE,UAAmC,EAAE;QAChE,KAAK,CAAC,2BAA2B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;IACjD,CAAC;CACF;AAED,MAAM,6BAA8B,SAAQ,kBAAkB;IAC5D,YAAY,OAAe,EAAE,UAAmC,EAAE;QAChE,KAAK,CAAC,wBAAwB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,uCAAwC,SAAQ,kBAAkB;IACtE,YAAY,OAAe,EAAE,UAAmC,EAAE;QAChE,KAAK,CAAC,6BAA6B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,yCAAyC,CAAC;IACxD,CAAC;CACF;AAED,MAAM,6BAA8B,SAAQ,kBAAkB;IAC5D,YAAY,OAAe,EAAE,UAAmC,EAAE;QAChE,KAAK,CAAC,iBAAiB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,KAAK,YAAY,kBAAkB,CAAC;AAC7C,CAAC;AAED,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,gCAAgC,EAChC,6BAA6B,EAC7B,uCAAuC,EACvC,6BAA6B,EAC7B,oBAAoB,GACrB,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-export { CodeServerBinaryNotFoundError, CodeServerKitError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupTimeoutError, isCodeServerKitError, } from "./errors.js";
-export { createCodeServerLaunch, launchCodeServerProcess } from "./launch.js";
+export { CodeServerBinaryNotFoundError, CodeServerEntrypointResolutionError, CodeServerInstallationResolutionError, CodeServerInvalidConfigurationError, CodeServerKitError, CodeServerLaunchPlanningError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupProbeError, CodeServerStartupTimeoutError, isCodeServerKitError, } from "./errors.js";
+export { launchCodeServerProcess } from "./launch.js";
+export { allocatePort, buildCodeServerArgs, buildCodeServerLaunchSpec, createCodeServerLaunch, createCodeServerLaunchPlan, normalizeTrustedOrigins, } from "./plan.js";
+export { DEFAULT_CODE_SERVER_PROFILE_ITEMS, DEFAULT_CODE_SERVER_PROFILE_PATHS, createCodeServerProfileSyncPlan, resolveCodeServerProfilePathMap, syncCodeServerProfile, } from "./profile.js";
+export { buildForwardedHeaders, isCodeServerHtmlResponse, normalizeTrustedOrigin, } from "./proxy.js";
 export { waitForCodeServerReady } from "./readiness.js";
 export { resolveCodeServerInstallation } from "./resolve.js";
-export type { CodeServerEntryKind, CodeServerInstallation, CodeServerLaunchMode, CodeServerLaunchOptions, CodeServerLaunchPlan, CodeServerProcessExit, CodeServerProcessHandle, CodeServerReadyOptions, CodeServerReadyResult, LaunchCodeServerProcessOptions, ResolveCodeServerInstallationOptions, } from "./types.js";
+export { buildPathBindings, createCodeServerLaunchSpec, formatCodeServerCommand, normalizeCodeServerStartupFailure, } from "./spec.js";
+export type { BuildForwardedHeadersOptions, CodeServerEntryKind, CodeServerHtmlResponseOptions, CodeServerInstallation, CodeServerLaunchMode, CodeServerLaunchOptions, CodeServerLaunchPlan, CodeServerLaunchSpec, CodeServerPathAccessMode, CodeServerPathBinding, CodeServerProcessExit, CodeServerProcessHandle, CodeServerProfileEntryKind, CodeServerProfileItem, CodeServerProfilePathMap, CodeServerProfileSkipReason, CodeServerProfileSyncEntry, CodeServerProfileSyncPlan, CodeServerProfileSyncResult, CodeServerReadyFailure, CodeServerReadyFailureProbe, CodeServerReadyOptions, CodeServerReadyResult, CreateCodeServerLaunchPlanOptions, CreateCodeServerProfileSyncPlanOptions, LaunchCodeServerProcessOptions, NormalizedCodeServerStartupFailure, ResolveCodeServerInstallationOptions, SyncCodeServerProfileOptions, } from "./types.js";
 export type { CodeServerKitErrorCode } from "./errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,gCAAgC,EAChC,6BAA6B,EAC7B,uCAAuC,EACvC,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,EAC9B,oCAAoC,GACrC,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,mCAAmC,EACnC,qCAAqC,EACrC,mCAAmC,EACnC,kBAAkB,EAClB,6BAA6B,EAC7B,gCAAgC,EAChC,6BAA6B,EAC7B,uCAAuC,EACvC,2BAA2B,EAC3B,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iCAAiC,EACjC,iCAAiC,EACjC,+BAA+B,EAC/B,+BAA+B,EAC/B,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,EACvB,iCAAiC,GAClC,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,6BAA6B,EAC7B,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,EACtB,qBAAqB,EACrB,iCAAiC,EACjC,sCAAsC,EACtC,8BAA8B,EAC9B,kCAAkC,EAClC,oCAAoC,EACpC,4BAA4B,GAC7B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,5 +1,9 @@
-export { CodeServerBinaryNotFoundError, CodeServerKitError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupTimeoutError, isCodeServerKitError, } from "./errors.js";
-export { createCodeServerLaunch, launchCodeServerProcess } from "./launch.js";
+export { CodeServerBinaryNotFoundError, CodeServerEntrypointResolutionError, CodeServerInstallationResolutionError, CodeServerInvalidConfigurationError, CodeServerKitError, CodeServerLaunchPlanningError, CodeServerPackageResolutionError, CodeServerPortAllocationError, CodeServerProcessExitedBeforeReadyError, CodeServerStartupProbeError, CodeServerStartupTimeoutError, isCodeServerKitError, } from "./errors.js";
+export { launchCodeServerProcess } from "./launch.js";
+export { allocatePort, buildCodeServerArgs, buildCodeServerLaunchSpec, createCodeServerLaunch, createCodeServerLaunchPlan, normalizeTrustedOrigins, } from "./plan.js";
+export { DEFAULT_CODE_SERVER_PROFILE_ITEMS, DEFAULT_CODE_SERVER_PROFILE_PATHS, createCodeServerProfileSyncPlan, resolveCodeServerProfilePathMap, syncCodeServerProfile, } from "./profile.js";
+export { buildForwardedHeaders, isCodeServerHtmlResponse, normalizeTrustedOrigin, } from "./proxy.js";
 export { waitForCodeServerReady } from "./readiness.js";
 export { resolveCodeServerInstallation } from "./resolve.js";
+export { buildPathBindings, createCodeServerLaunchSpec, formatCodeServerCommand, normalizeCodeServerStartupFailure, } from "./spec.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,gCAAgC,EAChC,6BAA6B,EAC7B,uCAAuC,EACvC,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,mCAAmC,EACnC,qCAAqC,EACrC,mCAAmC,EACnC,kBAAkB,EAClB,6BAA6B,EAC7B,gCAAgC,EAChC,6BAA6B,EAC7B,uCAAuC,EACvC,2BAA2B,EAC3B,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iCAAiC,EACjC,iCAAiC,EACjC,+BAA+B,EAC/B,+BAA+B,EAC/B,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,EACvB,iCAAiC,GAClC,MAAM,WAAW,CAAC"}

package/dist/launch.d.ts

@@ -1,5 +1,4 @@
-import type { CodeServerLaunchOptions, CodeServerLaunchPlan, CodeServerProcessHandle, LaunchCodeServerProcessOptions } from "./types.js";
-declare function createCodeServerLaunch(options: CodeServerLaunchOptions): Promise<CodeServerLaunchPlan>;
+import type { CodeServerProcessHandle, LaunchCodeServerProcessOptions } from "./types.js";
 declare function launchCodeServerProcess(options: LaunchCodeServerProcessOptions): Promise<CodeServerProcessHandle>;
-export { createCodeServerLaunch, launchCodeServerProcess };
+export { launchCodeServerProcess };
 //# sourceMappingURL=launch.d.ts.map

package/dist/launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,uBAAuB,EACvB,oBAAoB,EAEpB,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAKpB,iBAAe,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkDrG;AAED,iBAAe,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA6DhH;AAsOD,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,CAAC"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAEpB,iBAAe,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAwEhH;AAiBD,OAAO,EAAE,uBAAuB,EAAE,CAAC"}