SCTree

SCTree is the language and CLI for Software Construction Tree documents.

Software Construction Tree, or SCT, is the design system. SCTree is the notation used to describe a project structure in .sctree files. An SCTree document describes the planned folder and file structure of a software project in a small, readable syntax that can be rendered as a terminal tree, HTML preview, or text file.

It is meant to sit between project planning and implementation: a lightweight artifact that communicates how a project should be shaped before every file has to exist on disk.

Installation

Install globally:

npm install -g sctree-cli

When npm's global binary directory is on your PATH, the command is available as:

sctree

If your shell cannot find sctree, check npm's global install prefix:

npm prefix -g

On macOS/Linux, global binaries are usually inside the bin folder under that prefix. Make sure that folder is included in your PATH.

You can also run the sctree binary without a global install:

npx sctree-cli --help
npx sctree-cli init

Quick Start

Create a new SCTree document interactively:

sctree init

Create one immediately with defaults:

sctree init -y

Create one with specific metadata:

sctree init -y --name ApiProject --language csharp --framework aspnet-core

Scan an existing project into an SCTree document:

sctree scan --name ExistingProject

SCTree files are written to .out/ by default.

Example .sctree File

name                    = "Project"
type                    = "none"
language                = "typescript"
framework               = "none"
version                 = "0.1.0"
description             = "A planned project structure."

root Project {
  file .gitignore
  folder src {
    file index.ts
  }
}

Commands

Init

sctree init
sctree init -y
sctree init --yes
sctree init --y

init creates a new .sctree document, plus .sctreeignore and sctree.config.json in the project root. The -y and --yes flags skip prompts and use defaults for missing values.

Add

Add a file:

sctree add file users.controller.ts src/modules/users

Add a folder:

sctree add folder users src/modules

Use the shorthand file form:

sctree add users.controller.ts src/modules/users

Add multiple files or folders at once:

sctree add file -c users.controller.ts users.service.ts -d src/modules/users
sctree add folder -c users posts comments -d src/modules

Remove

Remove every matching file or folder name:

sctree rm users.controller.ts

Remove a matching entry under a specific folder:

sctree rm users.controller.ts src/modules/users

If the target is a folder, the folder and its children are removed from the SCTree tree.

Scan

Generate a .sctree document from the current project structure:

sctree scan

Set metadata while scanning:

sctree scan --name ApiProject --language csharp --framework aspnet-core

Overwrite an existing generated file:

sctree scan --force

Update

Scan the current project and add missing filesystem entries to the active .sctree document:

sctree update

Render

Render the tree in the terminal:

sctree render

Render an HTML preview:

sctree render --html

Render a text preview file:

sctree render --txt

Preview files are written to .out/ beside the .sctree file.

Ignore And Config Files

Use .sctreeignore to exclude paths from sctree scan and sctree update.

node_modules
dist
.out
coverage

Use sctree.config.json to opt into filesystem changes when sctree add or sctree rm is called.

{
	"filesystem": {
		"applyOnAdd": false,
		"applyOnRemove": false
	}
}

Both settings default to false, so add/remove only update the .sctree document unless you explicitly enable filesystem changes.

Supported Options

Current language options:

• typescript
• javascript
• csharp

Current framework options are language-dependent.

TypeScript:

• none
• node
• express
• nestjs
• react

JavaScript:

• none
• node
• express
• react

C#:

• none
• aspnet-core

Documentation

For more details about the language, syntax, parser rules, templates, and design direction, see:

• SCTree intro
• SCTree v2 specification