@nimbus-sh/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -13,6 +13,9 @@
 export { NimbusWorkspace } from './workspace/nimbus-workspace.js';
 export type { NimbusWorkspaceOptions } from './workspace/nimbus-workspace.js';
 export type { SqlDatabase, SqlTransactions, SqlRow, SqlValue, TransactionHost, } from './runtime/os-contracts.js';
+export { seedRuntimePackage } from './runtime/runtime-package.js';
+export type { RuntimePackage, SeededRuntime } from './runtime/runtime-package.js';
+export type { ManifestEntrypoint, ManifestFile, RuntimeManifest, } from './runtime/runtime-manifest.js';
 export { localFacetHost } from './runtime/local-facet-host.js';
 export type { Facet, FacetBindings, FacetFn, FacetHost, FacetSpec, FacetSubmitOptions, } from './runtime/facet-host.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;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,YAAY,EACV,WAAW,EACX,eAAe,EACf,MAAM,EACN,QAAQ,EACR,eAAe,GAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,YAAY,EACV,KAAK,EACL,aAAa,EACb,OAAO,EACP,SAAS,EACT,SAAS,EACT,kBAAkB,GACnB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,YAAY,EACV,WAAW,EACX,eAAe,EACf,MAAM,EACN,QAAQ,EACR,eAAe,GAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClF,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,eAAe,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,YAAY,EACV,KAAK,EACL,aAAa,EACb,OAAO,EACP,SAAS,EACT,SAAS,EACT,kBAAkB,GACnB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -11,4 +11,5 @@
  * depends on this package.
  */
 export { NimbusWorkspace } from './workspace/nimbus-workspace.js';
+export { seedRuntimePackage } from './runtime/runtime-package.js';
 export { localFacetHost } from './runtime/local-facet-host.js';

package/dist/runtime/runtime-package.d.ts

@@ -0,0 +1,63 @@
+/**
+ * runtime-package.ts — a runtime that arrived with the code, rather than over
+ * the network.
+ *
+ * `nimbus install <name>` reads a catalog out of R2 and writes the result into
+ * `~/.nimbus/runtimes/<name>/<version>/`. That is the Cloudflare deployment's
+ * answer to "where do the bytes come from", and it needs a bucket, a binding
+ * and a colo cache. An embedder who ran `npm i @nimbus-sh/runtime-bash` has
+ * already answered the same question: the bytes are on disk beside their
+ * manifest, fetched and integrity-checked by npm before any of this ran.
+ *
+ * So this is the second publisher, not the second package manager. It writes
+ * the SAME tree at the SAME path from the SAME manifest — `installRoot()`,
+ * `parseRuntimeManifest()`, one file per `manifest.files` entry — so
+ * `listInstalledManifests` and `rehydrateInstalledRuntimes` cannot tell which
+ * one ran, and a workspace behaves identically either way.
+ *
+ * Trust: R2 is verified against a digest chain rooted in a build-time pin
+ * because `caches.default` is shared across tenants and R2 keys are not
+ * content-addressed. A runtime package's root of trust is npm's own tarball
+ * integrity, which the install already checked; from there the manifest's
+ * per-file digests are re-verified here for exactly the reason the R2 path
+ * verifies them — these blobs are interpreters, so bytes that reach the
+ * filesystem are bytes that execute.
+ */
+import type { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+import { type ManifestFile, type RuntimeManifest } from './runtime-manifest.js';
+/**
+ * An installed npm package holding one runtime.
+ *
+ * The published packages (`@nimbus-sh/runtime-bash`,
+ * `@nimbus-sh/runtime-cpython`) are the implementations; each is a manifest,
+ * the content-addressed blobs it names, and the eight lines of `node:fs` that
+ * read them. The port is here rather than in those packages because the
+ * FILESYSTEM is what a runtime is, and this is the half that knows it.
+ *
+ * `readBlob` takes the whole manifest entry rather than a bare key, mirroring
+ * `fetchBlob` in the Cloudflare catalog: a key and the digest that vouches for
+ * it never travel as separate arguments, so there is no call in which they can
+ * disagree.
+ */
+export interface RuntimePackage {
+    readonly manifest: RuntimeManifest;
+    readBlob(file: ManifestFile): Uint8Array | Promise<Uint8Array>;
+}
+export interface SeededRuntime {
+    readonly name: string;
+    readonly version: string;
+    /** VFS path of the install root, e.g. `home/user/.nimbus/runtimes/bash/5.2.37`. */
+    readonly root: string;
+    /** False when the runtime was already installed at `root` and nothing was written. */
+    readonly written: boolean;
+}
+/**
+ * Write a runtime package into the filesystem as an install.
+ *
+ * Idempotent on the same rule the package manager uses: a `manifest.json`
+ * already at the install root means the install completed, and the root
+ * carries the version, so a package upgrade lands beside its predecessor
+ * rather than half over it.
+ */
+export declare function seedRuntimePackage(vfs: CredentialedVfs, homeDir: string, runtimePackage: RuntimePackage): Promise<SeededRuntime>;
+//# sourceMappingURL=runtime-package.d.ts.map

package/dist/runtime/runtime-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-package.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,aAAa,CAAC,CAsBxB"}

package/dist/runtime/runtime-package.js

@@ -0,0 +1,66 @@
+/**
+ * runtime-package.ts — a runtime that arrived with the code, rather than over
+ * the network.
+ *
+ * `nimbus install <name>` reads a catalog out of R2 and writes the result into
+ * `~/.nimbus/runtimes/<name>/<version>/`. That is the Cloudflare deployment's
+ * answer to "where do the bytes come from", and it needs a bucket, a binding
+ * and a colo cache. An embedder who ran `npm i @nimbus-sh/runtime-bash` has
+ * already answered the same question: the bytes are on disk beside their
+ * manifest, fetched and integrity-checked by npm before any of this ran.
+ *
+ * So this is the second publisher, not the second package manager. It writes
+ * the SAME tree at the SAME path from the SAME manifest — `installRoot()`,
+ * `parseRuntimeManifest()`, one file per `manifest.files` entry — so
+ * `listInstalledManifests` and `rehydrateInstalledRuntimes` cannot tell which
+ * one ran, and a workspace behaves identically either way.
+ *
+ * Trust: R2 is verified against a digest chain rooted in a build-time pin
+ * because `caches.default` is shared across tenants and R2 keys are not
+ * content-addressed. A runtime package's root of trust is npm's own tarball
+ * integrity, which the install already checked; from there the manifest's
+ * per-file digests are re-verified here for exactly the reason the R2 path
+ * verifies them — these blobs are interpreters, so bytes that reach the
+ * filesystem are bytes that execute.
+ */
+import { sha256Hex } from '../_shared/crypto.js';
+import { installRoot } from './installed-runtimes.js';
+import { parseRuntimeManifest, } from './runtime-manifest.js';
+/**
+ * Write a runtime package into the filesystem as an install.
+ *
+ * Idempotent on the same rule the package manager uses: a `manifest.json`
+ * already at the install root means the install completed, and the root
+ * carries the version, so a package upgrade lands beside its predecessor
+ * rather than half over it.
+ */
+export async function seedRuntimePackage(vfs, homeDir, runtimePackage) {
+    const manifest = parseRuntimeManifest(runtimePackage.manifest);
+    const root = installRoot(homeDir, manifest.name, manifest.version);
+    if (vfs.exists(`${root}/manifest.json`)) {
+        return { name: manifest.name, version: manifest.version, root, written: false };
+    }
+    vfs.mkdir(root, { recursive: true });
+    for (const file of manifest.files) {
+        const target = `${root}/${file.path}`;
+        const parent = target.slice(0, target.lastIndexOf('/'));
+        if (!vfs.exists(parent))
+            vfs.mkdir(parent, { recursive: true });
+        vfs.writeFile(target, await verifiedBlob(manifest, runtimePackage, file));
+    }
+    // Last, where the R2 installer writes it first: that one has `--reinstall`
+    // to force a redo, and this one has no verb at all, so a manifest sitting
+    // beside a half-written tree would report a broken runtime as installed for
+    // the life of the filesystem.
+    vfs.writeFile(`${root}/manifest.json`, JSON.stringify(manifest, null, 2));
+    return { name: manifest.name, version: manifest.version, root, written: true };
+}
+async function verifiedBlob(manifest, runtimePackage, file) {
+    const bytes = await runtimePackage.readBlob(file);
+    const actual = await sha256Hex(bytes);
+    if (actual !== file.sha256) {
+        throw new Error(`${manifest.name}@${manifest.version}: sha256 mismatch for ${file.path} — manifest expects `
+            + `${file.sha256}, ${file.content} holds ${actual}`);
+    }
+    return bytes;
+}

package/dist/runtime/runtime-registry.d.ts

@@ -154,8 +154,9 @@ export interface ShellRegistry {
 export declare function buildRuntimeHandler(spec: RuntimeSpec, ctx0: {
     vfs: SqliteVFS;
     /** Lazy esbuild initialiser. Called once per first .ts/.tsx/.jsx
-     *  invocation — the host owns the init lifecycle. */
-    getEsbuild(): EsbuildService;
+     *  invocation — the host owns the init lifecycle, including whether
+     *  the module is loaded eagerly or on this call. */
+    getEsbuild(): EsbuildService | Promise<EsbuildService>;
     registry: ShellRegistry;
 }): (ctx: any) => Promise<number>;
 //# sourceMappingURL=runtime-registry.d.ts.map

package/dist/runtime/runtime-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-registry.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-registry.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-registry.ts"],"names":[],"mappings":"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"}

package/dist/runtime/runtime-registry.js

@@ -283,7 +283,7 @@ export function buildRuntimeHandler(spec, ctx0) {
             scriptExt === '.jsx' ||
             needsEsmTransform) {
             try {
-                const eb = getEsbuild();
+                const eb = await getEsbuild();
                 const loader = scriptExt === '.tsx' ? 'tsx' :
                     scriptExt === '.jsx' ? 'jsx' :
                         scriptExt === '.ts' ? 'ts' :

package/dist/workspace/nimbus-workspace.d.ts

@@ -3,24 +3,32 @@
  *
  * A workspace is a durable filesystem plus a shell over it. It owns no
  * transport, no session, no socket and no Durable Object: the host supplies
- * SQLite and gets back `.fs` and `.exec`. That is what makes it embeddable in
- * a Durable Object that is already busy powering something else, and what
- * makes it runnable in a plain bun process over `bun:sqlite`.
+ * the filesystem and gets back `.fs`, `.exec`, and a command registry to add
+ * to. That is what makes it embeddable in a Durable Object that is already
+ * busy powering something else, and what makes it runnable in a plain bun
+ * process over `bun:sqlite`.
  *
- * The composition here is not new. It is the one `session/init.ts` performs,
- * lifted out of the session so there is one recipe rather than one per caller
- * — five unit tests were already hand-rolling it, one of them reaching a
- * private field to do so. The boot itself still belongs to `Sandbox.create`;
- * this adds only what a durable, credentialed filesystem needs on top and
- * nothing the sandbox already knows how to do.
+ * The composition here is not new. It is the one `session/init.ts` performed
+ * inline, lifted out of the session so there is one recipe rather than one per
+ * caller — the session now reads its kernel, shell and registry off a
+ * workspace, and five unit tests were already hand-rolling the same steps.
+ *
+ * Deliberately not `Sandbox.create`, which is the lifo demo sandbox's boot
+ * rather than this one: it registers `systemctl`, `tunnel` and the network
+ * command set, boots enabled service units out of `/etc/systemd`, and starts
+ * the shell before the host can register a command of its own. A session
+ * routed through it would silently acquire all of that.
  */
+import { Kernel } from '../substrate/lifo/kernel/index.js';
+import { Shell } from '../substrate/lifo/shell/Shell.js';
+import type { ShellCommandIdentity } from '../substrate/lifo/shell/Shell.js';
+import type { CommandRegistry } from '../substrate/lifo/commands/registry.js';
 import type { CommandResult, RunOptions, SandboxFs } from '../substrate/lifo/sandbox/types.js';
-import type { Kernel } from '../substrate/lifo/kernel/index.js';
-import type { Shell } from '../substrate/lifo/shell/Shell.js';
 import type { ITerminal } from '../substrate/lifo/terminal/ITerminal.js';
 import { SqliteVFS } from '../vfs/sqlite-vfs.js';
 import type { SqlDatabase, TransactionHost } from '../runtime/os-contracts.js';
 import type { FacetHost } from '../runtime/facet-host.js';
+import { type RuntimePackage } from '../runtime/runtime-package.js';
 export interface NimbusWorkspaceOptions {
     /** The host's SQLite. In a Durable Object: `ctx.storage.sql`. */
     readonly sql: SqlDatabase;
@@ -33,18 +41,55 @@ export interface NimbusWorkspaceOptions {
      */
     readonly transactions?: TransactionHost;
     /**
-     * Process-id generation. The workspace revokes every append capability at
-     * or below `generation * 1_000_000` before serving anything, so a value
-     * that repeats across restarts hands a dead process live write authority.
-     * Hosts that persist must supply a counter that never repeats.
+     * The filesystem already open over `sql`, for a host that has one.
+     *
+     * A Durable Object does: its installer, its git commands and its RPC
+     * surfaces read those rows without a shell in sight, and they hold a
+     * SqliteVFS from the first request that needed one. It must hand over THAT
+     * one — a second SqliteVFS over the same database is a second cache, and
+     * one of the two will serve a stale read. Such a host has also already
+     * revoked the previous generation's append writers, which is why that only
+     * happens below when the workspace is the one opening the filesystem.
+     */
+    readonly vfs?: SqliteVFS;
+    /**
+     * Process-id generation. Two things rest on it: the workspace revokes every
+     * append capability at or below `generation * 1_000_000` before serving
+     * anything, and the wasm runner allocates pids above it. A value that
+     * repeats across restarts hands a dead process live write authority, so
+     * hosts that persist must supply a counter that never repeats.
      */
     readonly generation?: number;
     /** Top-level directories backed by `sql`. Defaults to DEFAULT_MOUNT_POINTS. */
     readonly mounts?: readonly string[];
+    /** Overlaid on the Nimbus default environment. */
     readonly env?: Record<string, string>;
     readonly cwd?: string;
     /** Absent means headless: `.exec` captures output and nothing is drawn. */
     readonly terminal?: ITerminal;
+    /**
+     * Who the shell acts as, when the host keeps a process table that can answer
+     * for it. Absent, commands run as uid 1000 with a umask of 022 and no
+     * process behind them, which is the Shell's own default.
+     */
+    readonly identity?: ShellCommandIdentity;
+    /**
+     * Language runtimes to install before the shell is served, as npm packages
+     * the embedder imported (`@nimbus-sh/runtime-bash`,
+     * `@nimbus-sh/runtime-cpython`).
+     *
+     * A Durable Object gets these from R2 through `nimbus install`; an embedder
+     * off Cloudflare has no bucket and needs none, because npm already fetched
+     * and integrity-checked the same bytes. Both write the same tree at the same
+     * path, so what is installed here is indistinguishable from what is
+     * installed there — see runtime/runtime-package.ts.
+     *
+     * Independent of `facets`: this decides what the filesystem HOLDS, and
+     * `facets` decides whether anything can run it. A workspace given runtimes
+     * and no facet host installs them and still answers "command not found",
+     * because it still has nothing that could compile a module.
+     */
+    readonly runtimes?: readonly RuntimePackage[];
     /**
      * Where WebAssembly runs.
      *
@@ -56,21 +101,24 @@ export interface NimbusWorkspaceOptions {
      * and `wasm-runner` joins them, which is what makes a `\0asm` file on the
      * PATH executable (see shell/exec-dispatch.ts).
      *
-     * A Durable Object passes the workerd host (`@nimbus-sh/worker`'s
-     * `loaderFacetHost`); a plain process passes `localFacetHost()`.
+     * A plain process passes `localFacetHost()`. A Durable Object passes nothing
+     * here and registers its own runners instead, because the ones it needs
+     * carry REPLs and a resident-process substrate this cannot reach.
      */
     readonly facets?: FacetHost;
 }
 /**
  * A durable filesystem and a shell over it.
  *
- * Created with {@link NimbusWorkspace.create} rather than `new` because the
- * boot it delegates to sources `/etc/profile`, which is genuinely async. A
- * Durable Object constructor cannot await, so a host constructs the workspace
- * in its first request rather than in its constructor.
+ * The composition itself is synchronous. {@link create} awaits only the
+ * optional work — installing runtime packages, loading the wasm runner modules
+ * — so a host that asks for neither is never suspended between mounting the
+ * filesystem and registering the commands. A Durable Object needs that: it
+ * must not take delivery of an event with a half-built shell. The remaining
+ * async step, running the user's login files, is {@link start}, which the host
+ * calls once its own commands are in place.
  */
 export declare class NimbusWorkspace {
-    private readonly sandbox;
     private readonly sql;
     /**
      * Credentialed and mount-aware. Acts as the session user, never as the
@@ -82,9 +130,26 @@ export declare class NimbusWorkspace {
     readonly vfs: SqliteVFS;
     readonly kernel: Kernel;
     readonly shell: Shell;
+    /** What the shell resolves a command name against. A host adds its own. */
+    readonly registry: CommandRegistry;
+    /**
+     * The environment the shell was composed with. The shell's own copy drifts
+     * from this one the moment the user exports anything; this is what a host
+     * hands to a subordinate shell it starts itself.
+     */
+    readonly env: Record<string, string>;
+    private readonly commands;
     private constructor();
     static create(options: NimbusWorkspaceOptions): Promise<NimbusWorkspace>;
     exec(command: string, options?: RunOptions): Promise<CommandResult>;
+    /**
+     * Apply the login files, and begin reading the terminal when there is one.
+     *
+     * Separate from {@link create} because a host with commands of its own must
+     * register them first: `/etc/profile` and `~/.nimbusrc` are the user's
+     * files, and either may name a command the host has yet to supply.
+     */
+    start(): Promise<void>;
     /**
      * Files, directories and bytes this workspace occupies.
      *
@@ -107,4 +172,19 @@ export declare class NimbusWorkspace {
      */
     destroy(): void;
 }
+/**
+ * The directories and account files the shell cannot start without.
+ *
+ * Idempotent by construction: every write is guarded by an existence check, so
+ * a workspace reopened over a populated database keeps whatever the user did
+ * to these files. `/etc/passwd` and `/etc/group` are load-bearing rather than
+ * decorative — `id`, `chown` and `su` resolve names through them.
+ *
+ * What a PRODUCT puts in a fresh filesystem — a banner, a welcome file, a
+ * starter app — is not here. This is the base an OS needs in order to boot,
+ * and it is exported because a host may need the filesystem before it needs a
+ * shell: the Nimbus session seeds its starter project for a browser that hits
+ * `/preview` without ever opening a terminal.
+ */
+export declare function seedBaseFilesystem(vfs: SqliteVFS, mounts: readonly string[]): void;
 //# sourceMappingURL=nimbus-workspace.d.ts.map

package/dist/workspace/nimbus-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nimbus-workspace.d.ts","sourceRoot":"","sources":["../../src/workspace/nimbus-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,SAAS,EAAqB,MAAM,sBAAsB,CAAC;AAGpE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAU1D,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAC9B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAaxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAdtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,OAAO;WAiBM,MAAM,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IAmC9E,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAInE;;;;;;OAMG;IACH,KAAK,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAK3D;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAKhB"}
+{"version":3,"file":"nimbus-workspace.d.ts","sourceRoot":"","sources":["../../src/workspace/nimbus-workspace.ts"],"names":[],"mappings":"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"}