# How Local Folder Projects Are Referenced in Nodeterm's workspace.json

> Learn how Nodeterm references local folder projects using the cwd field in workspace.json. Understand absolute paths and schema definitions for efficient project management.

- Repository: [eneskirca/nodeterm](https://github.com/eneskirca/nodeterm)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Nodeterm references local folder projects via the `cwd` field in [`workspace.json`](https://github.com/eneskirca/nodeterm/blob/main/workspace.json), which stores the absolute filesystem path, while the schema enforces that each entry contains exactly one of either `cwd` (local) or `ssh` (remote) per the definitions in [`src/core/workspace-files.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-files.ts).**

Nodeterm maintains a machine-local index file named [`workspace.json`](https://github.com/eneskirca/nodeterm/blob/main/workspace.json) to persist all open projects across application sessions. Each entry in this JSON array represents a single project workspace and must specify its physical location using either a local folder reference or a remote SSH connection. The mechanism that distinguishes these project types is strictly enforced at the schema level within the `eneskirca/nodeterm` codebase.

## The `cwd` Field: Absolute Path Reference

For local folder projects, the definitive link to the filesystem is the **`cwd`** property. This field contains the absolute path to the folder on the user's machine, stored verbatim in [`workspace.json`](https://github.com/eneskirca/nodeterm/blob/main/workspace.json) and read back on every application start to re-associate the project with the correct directory.

According to the source code in [`src/core/workspace-files.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-files.ts) (lines 105-106), the schema comment explicitly states that a workspace entry must contain **exactly one** of:

- **`cwd`** — a string representing the local folder reference
- **`ssh`** — an object containing remote connection details

This mutual exclusivity ensures unambiguous project type detection during load operations.

## Workspace Entry Structure

When Nodeterm persists a local project, it writes an entry object to [`workspace.json`](https://github.com/eneskirca/nodeterm/blob/main/workspace.json) with the following structure:

```typescript
{
  "id": "c3f1e2b9-7a4d-4f1a-9c8e-1a2b3c4d5e6f",
  "cwd": "/home/user/my-project",   // Absolute path to local folder
  "title": "My Project",
  "rev": 42,
  "viewport": { "x": 0, "y": 0, "zoom": 1.0 }
  // Additional properties: settings, nodes, canvas state
}

```

The `id` provides a unique identifier for the workspace tab, while `cwd` serves as the canonical reference to the project root. If the folder at the specified `cwd` is missing when the application loads, Nodeterm treats the entry as unavailable and displays a placeholder tab, though the path value remains preserved in the index.

## Loading and Resolution Logic

The resolution of local folder references occurs in [`src/core/workspace-store.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-store.ts). During initialization, the application reads [`workspace.json`](https://github.com/eneskirca/nodeterm/blob/main/workspace.json) (referenced around lines 1030-1032 in the source) and iterates through the entries array to reconstruct the workspace state.

For each entry containing a `cwd` value, Nodeterm validates the path string and attempts to locate the folder on the host filesystem. The store provides helper methods to retrieve the local path:

```typescript
// src/core/workspace-store.ts
function getLocalFolder(projectId: string): string | undefined {
  const entry = workspaceIndex.entries.find(e => e.id === projectId);
  return entry?.cwd;   // Returns the folder path if this is a local project
}

```

If the folder cannot be accessed, the application marks the project as detached but preserves the `cwd` value for potential reconnection.

## Schema Validation and Type Safety

The TypeScript definitions in [`src/core/workspace-files.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-files.ts) enforce the "exactly one" constraint through union types or conditional validation logic. This prevents malformed entries where both `cwd` and `ssh` are present or where neither is specified, ensuring the workspace store can definitively categorize each project as either local or remote without ambiguity.

## Summary

- **Local projects use `cwd`**: The `cwd` field in [`workspace.json`](https://github.com/eneskirca/nodeterm/blob/main/workspace.json) stores the absolute filesystem path to the project folder.
- **Schema exclusivity**: Each entry must contain exactly one of `cwd` (local) or `ssh` (remote), as defined in [`src/core/workspace-files.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-files.ts).
- **Resolution on load**: [`src/core/workspace-store.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-store.ts) reads the `cwd` value to locate and populate the project on startup.
- **Missing folder handling**: If the `cwd` path is inaccessible, Nodeterm displays an unavailable placeholder but retains the reference for future sessions.
- **Path persistence**: The absolute path is stored verbatim and remains the definitive link to the original project location.

## Frequently Asked Questions

### What is the difference between `cwd` and `ssh` in workspace.json?

The `cwd` property references a local filesystem folder using an absolute path (e.g., `/home/user/project`), while the `ssh` property contains configuration objects for remote SSH connections. According to the schema in [`src/core/workspace-files.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-files.ts) (lines 105-106), each workspace entry must contain exactly one of these two fields to clearly distinguish between local and remote project types.

### Can a project entry have both `cwd` and `ssh` references simultaneously?

No. The schema validation explicitly forbids entries from containing both fields. The source code in [`src/core/workspace-files.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-files.ts) mandates that a workspace entry must contain **exactly one** of either `cwd` or `ssh`, preventing ambiguous project location references.

### What happens if the folder specified in `cwd` is deleted or moved?

If the absolute path stored in `cwd` does not exist when Nodeterm loads the workspace, the application treats the entry as unavailable and renders a placeholder tab for that project. However, the `cwd` value persists in [`workspace.json`](https://github.com/eneskirca/nodeterm/blob/main/workspace.json), allowing the user to either restore the folder to the original location or manually update the path to reconnect the project.

### How does Nodeterm validate workspace.json entries during startup?

The workspace store logic in [`src/core/workspace-store.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/core/workspace-store.ts) validates that each entry contains a valid `id` and either a `cwd` or `ssh` field. When processing local entries, it checks the filesystem for the existence of the `cwd` path before attempting to load project nodes and canvas state, ensuring graceful handling of disconnected or relocated projects.