setup

Documentation

Overview

Package setup provides deterministic project-bootstrap verbs. The ScaffoldToolingResult JSON schema is stable — field names, types, and the closed enums for FileOutcome.Key and FileOutcome.Outcome must not change after first merge. Skills parse `nightgauge setup scaffold-tooling --json` output via fixed jq paths; any breaking change requires incrementing the V field.

The scaffold-tooling verb owns five embedded fixed templates (tsconfig, vitest, eslint, prettier, ci.yml) and the brownfield-safety invariant (never overwrite existing files; for ESLint and Prettier also probe legacy filenames). It replaces the ~303-line heredoc block in skills/smart-setup/SKILL.md Phase 4.5 (audit row B37).

Index

• Constants
• type DetectedDeps
• type FileOutcome
• type ScaffoldToolingOptions
• type ScaffoldToolingResult
  • func RunScaffoldTooling(ctx context.Context, opts ScaffoldToolingOptions) (*ScaffoldToolingResult, error)

Constants

const (
	TemplateKeyTsconfig = "tsconfig"
	TemplateKeyVitest   = "vitest"
	TemplateKeyESLint   = "eslint"
	TemplateKeyPrettier = "prettier"
	TemplateKeyCI       = "ci"
)

Template keys. Closed enum — adding a new key requires bumping the schema V.

const (
	OutcomeCreated           = "created"
	OutcomeSkippedExisting   = "skipped_existing"    // brownfield-safe: target file already present
	OutcomeSkippedMissingDep = "skipped_missing_dep" // template's parent dep missing from package.json
	OutcomeSkippedDisabled   = "skipped_disabled"    // not in --select list
	OutcomeError             = "error"               // write failure (permissions, etc.)
)

Outcome values. Closed enum — adding a new value requires bumping V.

Types

type DetectedDeps

type DetectedDeps struct {
	PackageJSONFound bool   `json:"package_json_found"`
	NodeVersion      string `json:"node_version"` // detected major or default "20"
	HasTypeScript    bool   `json:"has_typescript"`
	HasVitest        bool   `json:"has_vitest"`
	HasESLint        bool   `json:"has_eslint"`
	HasPrettier      bool   `json:"has_prettier"`
}

DetectedDeps records what the package.json scan found. Populated even when no package.json is present so the report stays self-describing.

type FileOutcome

type FileOutcome struct {
	Key     string `json:"key"`     // closed enum (TemplateKey*)
	Path    string `json:"path"`    // path relative to Workdir
	Outcome string `json:"outcome"` // closed enum (Outcome*)
	Reason  string `json:"reason"`  // human-readable detail (may be empty)
	Bytes   int    `json:"bytes"`   // bytes written (0 when skipped)
}

FileOutcome records the result of one template emission.

type ScaffoldToolingOptions

type ScaffoldToolingOptions struct {
	// Workdir is the project root. When empty, the caller's CWD is used.
	Workdir string
	// Select is the comma-list of template keys to emit. When empty or nil,
	// all five keys are selected.
	Select []string
	// DryRun reports outcomes with Bytes set to template length but does not
	// write any files.
	DryRun bool
}

ScaffoldToolingOptions controls a single run.

type ScaffoldToolingResult

type ScaffoldToolingResult struct {
	V        int           `json:"v"`        // schema version, always 1
	Workdir  string        `json:"workdir"`  // absolute path
	Selected []string      `json:"selected"` // requested template keys (post-normalize)
	Detected DetectedDeps  `json:"detected"` // dep + version detection report
	Outcomes []FileOutcome `json:"outcomes"` // one entry per requested template
	Warnings []string      `json:"warnings"` // non-fatal issues
}

ScaffoldToolingResult is the stable v1 JSON output schema for `nightgauge setup scaffold-tooling`. Field names and the closed enums for FileOutcome.Key and FileOutcome.Outcome are stable — adding a new value requires bumping V.

func RunScaffoldTooling

func RunScaffoldTooling(ctx context.Context, opts ScaffoldToolingOptions) (*ScaffoldToolingResult, error)

RunScaffoldTooling resolves workdir, detects dependencies via package.json, and emits each selected template under workdir. Existing files are never overwritten — they are recorded as OutcomeSkippedExisting. Templates that require a missing devDep are recorded as OutcomeSkippedMissingDep. Per-file write errors land in Outcomes[i].Outcome=OutcomeError; only hard input errors (unresolvable workdir, unknown template key) return non-nil err.