# @causa/workspace-core

> The Causa workspace module providing core function definitions and some implementations.

Latest version **1.4.0** (published 2026-08-26) · ISC license · 0 weekly downloads

## Install

```sh
npm install @causa/workspace-core
pnpm add @causa/workspace-core
yarn add @causa/workspace-core
bun add @causa/workspace-core
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2026-08-26 |
| First published | 2023-05-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 14 |
| Unpacked size | 526.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Maintainers | flovouin |

## Links

- npm: https://www.npmjs.com/package/@causa/workspace-core
- Repository: https://github.com/causa-io/workspace-module-core
- Homepage: https://github.com/causa-io/workspace-module-core#readme
- Issues: https://github.com/causa-io/workspace-module-core/issues
- npm.io page: https://npm.io/package/@causa/workspace-core

## Dependencies (14)

- [ajv](https://npm.io/package/ajv.md) ^8.20.0
- [pino](https://npm.io/package/pino.md) ^10.3.1
- [yaml](https://npm.io/package/yaml.md) ^2.9.0
- [expect](https://npm.io/package/expect.md) ^30.4.1
- [globby](https://npm.io/package/globby.md) ^16.2.4
- [json-e](https://npm.io/package/json-e.md) ^4.8.4
- [@causa/cli](https://npm.io/package/@causa/cli.md) ^1.0.0
- [micromatch](https://npm.io/package/micromatch.md) ^4.0.8
- [class-validator](https://npm.io/package/class-validator.md) ^0.15.1
- [@causa/workspace](https://npm.io/package/@causa/workspace.md) ^1.0.2
- [class-transformer](https://npm.io/package/class-transformer.md) ^0.5.1
- [@scalar/json-magic](https://npm.io/package/@scalar/json-magic.md) ^0.13.2
- [@scalar/openapi-parser](https://npm.io/package/@scalar/openapi-parser.md) ^0.28.16
- [@anthropic-ai/sandbox-runtime](https://npm.io/package/@anthropic-ai/sandbox-runtime.md) 0.0.73

## Recent versions

- 1.4.0 (latest) — 2026-08-26
- 0.35.0-beta.7 (beta) — 2026-06-08
- 1.3.0 — 2026-07-24
- 1.2.1 — 2026-06-29
- 1.2.0 — 2026-06-29
- 1.1.0 — 2026-06-11
- 1.0.1 — 2026-06-09
- 1.0.0 — 2026-06-09
- 0.35.0-beta.6 — 2026-05-27
- 0.35.0-beta.4 — 2026-05-22
- 0.35.0-beta.3 — 2026-05-21
- 0.35.0-beta.2 — 2026-05-21
- 0.35.0-beta.1 — 2026-05-18
- 0.34.0 — 2026-05-04
- 0.33.0 — 2026-04-29
- … 44 more at https://npm.io/package/@causa/workspace-core/versions

## README

# `@causa/workspace-core` module

This repository contains the source code for the `@causa/workspace-core` Causa module. It provides the implementations of many `cs` commands. It also provides definitions for commands that are meant to be implemented by other modules, depending on the project types and/or languages. For more information about the Causa CLI `cs`, checkout [its repository](https://github.com/causa-io/cli).

## ➕ Requirements

The core module requires Git and [Docker](https://www.docker.com/) for some of its operations (e.g. reading Git commit SHAs when publishing artefacts, pushing Docker image when publishing service containers, etc).

## 🎉 Installation

Add `@causa/workspace-core` to your Causa configuration in `causa.modules`.

## 🔧 Configuration

Several configurations are defined in this module, first for some generic `project.type`s:

- `infrastructure` ([`InfrastructureConfiguration`](./src/configurations/infrastructure-project.ts)): Projects defining infrastructure as code.
- `serverlessFunctions` ([`ServerlessFunctionsConfiguration`](./src/configurations/infrastructure-project.ts)): Projects defining serverless functions, meant to be run on some `serverlessFunctions.platform` (e.g. AWS Lambda, Google Cloud Functions).
- `serviceContainer` ([`ServiceContainerConfiguration`](./src/configurations/service-container-project.ts)): Projects defining a service, meant to be run as a container on some `serviceContainer.platform` (e.g. Kubernetes, Cloud Run, AWS ECS).

This module also exposes the [`DockerConfiguration`](./src/configurations/docker.ts), which is used by the `DockerService`, exposing usual Docker commands.

It also exposes the [`EventsConfiguration`](./src/configurations/events.ts), which defines the configuration related to events and their topics (e.g. how to find topic schema files in the workspace).

The [`ModelConfiguration`](./src/configurations/model.ts) defines the configuration for business model definitions, and the related code generation utilities.

For OpenAPI generation, the [`OpenApiConfiguration`](./src/configurations/openapi.ts) defines a global (base) specification for workspace-wide information (e.g. `info`, `securitySchemes`, etc), as well as glob patterns for project-level specification files.

## ✨ Supported project types and commands

The core module defines and implements many base `cs` commands. As a Causa user, you may want to check the [CLI repository](https://github.com/causa-io/cli) instead. As a module developer, you may want to check the [definitions](./src/definitions/) and determine which ones are relevant to implement in your module.

### Commands

- `cs init`: Initializes the workspace. This is a no-op in most cases as the CLI takes care of bootstrapping the workspace before running. The core module does not provide any project-specific implementation.
- `cs configuration check`: Validates the workspace configuration against the combined JSON Schema from all modules. Use `--render` to render templates (without secrets) before validating, and `--projects` to validate each project's configuration independently.
- `cs emulators`: Provides the `list`, `start`, and `stop` commands. However no actual emulator is implemented by this module. Available emulators will depend on other loaded modules. `cs emulators start` writes the configuration returned by the emulators to `.causa/emulators.env`. It is intended to be loaded by tests and local runs. The location of the file can be changed using the `causa.emulators.environmentFile` configuration.
- `cs environment`: Provides the `prepare` and `deploy` commands, forwarding those infrastructure commands to the project configured in `infrastructure.environmentProject`.
- `cs events backfill` and `cs events cleanBackfill`: The common backfilling logic is implemented in this module. However, this logic requires several tech stack-specific functions to be implemented by other modules.
- `cs infrastructure`: Provides the `prepare` and `deploy` commands. Those commands run "infrastructure processors" before the actual infrastructure operation, and tear those down afterwards. The core module does not implement actual infrastructure operations, which depend on the project's language, e.g. `terraform`.
- `cs publish`: While many base commands (e.g. `cs build`) are straightforward and should be implemented by the modules handling the corresponding project types and languages, `cs publish` provides some logic around these base commands to both build and push a project's artefact. The artefact is tagged according to the passed value or format, e.g. `my-custom-tag` or `semantic`. (The latter will use the project's version as the tag.)
- `cs openapi generateSpecification`: At the workspace level, triggers the generation of the specification in each project and merges and bundles the outputs into a single file. At the project level, merges specification files matched by `openApi.specifications` globs (if set). To use other project-level generation implementations, simply leave the `openApi.specifications` unset.
- `cs diff`: Lists changed projects based on the output of `git diff`. This can be useful for CI workflows. This module entirely implements the logic, and no other module is expected to provide an implementation.
- `cs model generateCode`: Runs the code generators defined in the `model.codeGenerators` configuration.
- `cs scenario run <path>`: Loads a scenario YAML file and runs its steps, calling workspace functions in dependency order.

### Secrets backend

The core module implements a very basic secrets backend: `environmentVariable`. As the name suggests, it retrieves values from the process environment:

```yaml
secrets:
  mySecret:
    backend: environmentVariable
    name: SOME_ENV_VAR
```

## 📚 Definitions

The core module provides many Causa workspace function definitions. Some of those definitions are exposed as `cs` commands and provides the base functionalities for a Causa workspace. Some of the function definitions are implemented "generically" in this module, while others are meant to be implemented by other Causa modules, providing support of a specific project language or type.

This section provides pointers for Causa module developers. Workspace function definitions can be found in the [`./src/definitions`](./src/definitions/) directory. Those include:

- [Emulators](./src/definitions/emulator.ts): Modules exposing local emulators (e.g. of databases) should implement both `EmulatorStart` and `EmulatorStop` for each of them.
- [Environment](./src/definitions/environment.ts): Functions mapping to `cs environment` commands. Those are not meant to be implemented by other modules.
- [Event topic](./src/definitions/event-topic.ts): Functions related to event topics, e.g. backfilling. Modules providing support for a new project type should implement `EventTopicListReferencedInProject`. Modules providing tech stack or cloud provider support should implement the `EventTopicBroker*` functions, register `EventTopicCreateBackfillSource` implementations for the source schemes they handle (including the "no source" / broker-default case), and implement `EventTopicQueryEvents` so events published to a topic can be queried.
- [Infrastructure](./src/definitions/infrastructure.ts): Modules providing support for an Infrastructure as Code tool (e.g. Terraform, Pulumi) should implement the `InfrastructurePrepare` and `InfrastructureDeploy` functions.
- [Model](./src/definitions/model.ts): Modules providing support for a programming language can implement new code generators by extending `ModelRunCodeGenerator`. The schema-level functions `ModelSchemaParse` (parsing and loading schema files into the format-neutral model exposed in [`model.types.ts`](./src/definitions/model.types.ts)) and `ModelSchemaWrite` (creating, updating, deleting, or renaming a schema in a file) are implemented for JSONSchema in this module. Modules providing support for a database engine should register an implementation of `ModelSchemaExtractDatabase` that turns an object schema's causa extensions into a `SchemaDatabase` binding.
- [Project](./src/definitions/project.ts): Many of the definitions in this file should be implemented by modules providing support for a language and/or project type, e.g. `ProjectBuildArtefact`, `ProjectReadVersion`, `ProjectPushArtefact`, `ProjectGetArtefactDestination`.
- [OpenAPI](./src/definitions/openapi.ts): Functions related to OpenAPI specifications. `OpenApiGenerateSpecification` should be implemented by Causa modules providing support for a language / project type (if relevant).
- [Scenario](./src/definitions/scenario.ts): The `ScenarioRun` definition powering `cs scenario run`. The implementation is generic and shipped by this module — it dispatches to other workspace functions, so other modules only need to expose the functions referenced from scenario steps.
- [HTTP](./src/definitions/http.ts): The `HttpMakeRequest` function, useful as a scenario step (e.g. for end-to-end checks against a deployed service).
- [Database](./src/definitions/database.ts): The `DatabaseQueryRecords` function. Modules providing support for a database engine should register an implementation against their `engine` value.
- [Service container](./src/definitions/service-container.ts): The `ServiceContainerQueryLogs` function. Modules providing support for a deployment platform should register an implementation that fetches logs for a deployed service container.

## 🔨 Services

This module implements some [services](./src/services/) used by itself, but which might also come handy in other modules, namely:

- `ProcessService`: Provides a normalized way to spawn child processes, optionally inside an OS-level sandbox (see [Sandboxing](#-sandboxing) below).
- `GitService`: Runs `git` commands using the `ProcessService`.
- `DockerService`: Runs `docker` commands using the `ProcessService`.
- `DockerEmulatorService`: Provides a normalized way to starting and stopping containerized emulators. Also provides a way to wait for an emulator exposing an HTTP endpoint.
- `ServiceContainerBuilderService`: Provides the base logic to build service container images (using the `DockerService`). Language-specific modules can use this service and customize build parameters.

## 🔒 Sandboxing

The `ProcessService` can run a spawned process inside an OS-level sandbox (macOS Seatbelt or Linux Bubblewrap), powered by [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime). Sandboxing is opt-in and fails closed: a process runs unsandboxed unless it references a profile, and referencing a missing or invalid profile throws rather than running the process unrestricted.

Sandbox profiles are defined under `causa.sandboxes`, keyed by an arbitrary name:

```yaml
causa:
  sandboxes:
    install:
      network:
        allowedDomains: [registry.npmjs.org, '*.npmjs.org']
      filesystem:
        allowRead: ['~/.npm']
        allowWrite: ['~/.npm']
      credentials:
        environment:
          NPM_TOKEN:
            hosts: [registry.npmjs.org]
```

A profile controls:

- **Network** (`network`): `allowedDomains` is an allowlist (an empty or omitted list blocks all network access); `deniedDomains` takes precedence over it. Wildcards such as `*.example.com` are supported. Additional flags (`allowLocalBinding`, `allowUnixSockets`, `allowAllUnixSockets`) relax specific restrictions.
- **Filesystem** (`filesystem`): the workspace root is always readable and writable, and the home directory is always denied for reads. `denyRead`, `allowRead`, `allowWrite`, and `denyWrite` extend those defaults (re-allowed paths take precedence over denied ones).
- **Credentials** (`credentials.environment`): a map of environment variables, keyed by name, that must not be exposed in clear to the process. Each variable is replaced by an opaque sentinel inside the sandbox. The real value is injected by the host only into requests to the declared `hosts`. An empty `hosts` list denies the variable entirely (it is unset inside the sandbox).

## 🧱 Infrastructure processors

### `ProjectWriteConfigurations`

[ProjectWriteConfigurations](./src/functions/project-write-configurations.ts) is an infrastructure processor that writes the configuration of each and every project in the workspace to a single JSON file per project. This allows the configuration to be consumed by external systems that are not implemented in TypeScript and do not integrate directly with Causa. The output directory for the configuration files can be set in the `causa.projectConfigurationsDirectory` configuration, which defaults to `.causa/project-configurations`.

## 📫 Backfilling

One of Causa's features is the ability to backfill events to be processed by services. The `cs events backfill` command orchestrates the generic flow: temporary topic and trigger setup, resolving the source of events to publish, and driving the broker-specific publisher. Stack-specific logic lives in other modules through the `EventTopicBroker*` function definitions.

Triggers passed with `--trigger` are free-form URIs by default and are interpreted by the broker. Triggers matching the format `<projectPath>#<triggerName>[?<options>]` are treated as project-scoped: the workspace context is cloned for the referenced project (relative to the workspace root), and `EventTopicBrokerCreateTrigger` is called with a structured `{ name, options }` payload on that project-scoped context. Options are parsed as a URL query string into a `Record<string, string>`.

The events to publish are built by `EventTopicCreateBackfillSource`, which returns an `AsyncIterable<BackfillEvent>` passed to `EventTopicBrokerPublishEvents`. This module ships an implementation for `json://<glob>` sources (newline-delimited JSON files with `data`, optional `attributes`, and optional `key` fields). When no `--source` is passed, the broker module is expected to provide an implementation that yields from its default storage for the topic. Filtering, when supported, is applied inside the source implementation — the returned iterable yields only the events that should actually be published.

Passing `--autoClean` to `cs events backfill` makes the command wait for events to be processed once publishing succeeds, then run the equivalent of `cs events cleanBackfill` inline — so a single call handles publish, drain, and cleanup. The wait is delegated to `EventTopicBrokerWaitForProcessing`, which is broker-specific (timeout and "processed" semantics live there). On success no backfill file is written and the command outputs nothing. On any failure during publish, wait, or cleanup, the backfill file is written so `cs events cleanBackfill` can still be run manually.

## 🎬 Scenarios

Scenarios are YAML files that orchestrate calls to workspace functions, with templated arguments, dependency-driven scheduling, expectations, and retries. They are run with `cs scenario run <path>` (relative paths are resolved from the workspace root). The schema for a scenario file is shipped with this module at [`./src/scenarios/schemas/scenario.yaml`](./src/scenarios/schemas/scenario.yaml) and embedded under `dist/scenarios/schemas/` when published.

Step `args` and `expectations` are rendered with [json-e](https://json-e.js.org/) and have access to:

- `${ input('<name>') }` — resolves a scenario input.
- `${ output('<stepId>') }` — resolves another step's output (and is also used to detect cross-step dependencies).
- `${ configuration('<path>') }` — resolves a value from the workspace configuration.
- `${ str(<value>) }` — overrides the json-e builtin to also format `Date` values as ISO strings.
- `${ rand('uuid') }`, `${ rand('int', <min>, <max>) }`, `${ rand('float', <min>, <max>) }` — generates a random UUID, integer, or floating-point number (the bounded variants in `[min, max)`).

## 📈 Timelines

A timeline describes a view of one or several time-ordered sources (service logs and event topics) queried over a shared time window. This module only models timelines: there is no corresponding CLI command or workspace function. The `Timeline` type (and its children) is exported from the package root, and its schema is shipped at [`./src/timeline/schemas/timeline.yaml`](./src/timeline/schemas/timeline.yaml) and embedded under `dist/timeline/schemas/` when published.

---
_Source: https://npm.io/package/@causa/workspace-core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._