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

Nodeterm references local folder projects via the cwd field in 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.

Nodeterm maintains a machine-local index file named 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 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 (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 with the following structure:

{
  "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. During initialization, the application reads 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:

// 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 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 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.
• Resolution on load: 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 (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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}