scaffold

type EmbeddedTemplate struct {
	// NameValue is the template's wire name.
	NameValue string
	// SummaryValue is the one-line CLI help.
	SummaryValue string
	// Source is the embed.FS containing the template's source tree.
	// PathPrefix below points at the directory within it that is the
	// project root (so a `//go:embed all:templates/analytics-widgets`
	// FS with PathPrefix `templates/analytics-widgets` materialises
	// starting from the project root).
	Source fs.FS
	// PathPrefix is the directory inside Source whose contents are the
	// project root. The empty string means "the FS root itself".
	PathPrefix string
	// TextExts is the set of file extensions whose contents are treated as
	// text and run through the substitution table. Anything not listed is
	// copied byte-exact. A trailing-dotless ".go", ".yaml" form is expected;
	// matching is case-sensitive.
	TextExts []string
	// SubstitutionsFor returns the substitution table for one materialisation.
	// Called once per Materialise; the returned slice is read-only.
	SubstitutionsFor func(opts Options) []Substitution
	// PathRemap rewrites a project-relative source path to a different
	// destination path in the materialised project. The pairs are applied
	// in order as prefix substitutions: the first matching `From` prefix
	// is replaced with `To`. Used by templates whose in-repo layout
	// differs from the materialised layout — typically because Go's
	// `internal/` barrier prevents the framework's own tests from
	// importing the template's contract package, so the in-repo layout
	// uses a non-internal path and PathRemap re-applies the `internal/`
	// prefix on materialisation. Optional; nil/empty means a 1:1 copy.
	PathRemap []PathSubstitution
}

type GreetInput struct {
	// Name is who to greet. Required.
	Name string `json:"name"`
	// Greeting is the salutation to use; defaults to "Hello" when empty.
	Greeting string `json:"greeting,omitempty"`
}

type GreetOutput struct {
	// Message is the assembled greeting.
	Message string `json:"message"`
	// Length is the rune length of Message — a trivial derived field so the
	// output struct is not a single-field shell.
	Length int `json:"length"`
}

type Options struct {
	// Name is the project name — also the directory name, the manifest name,
	// and the MCP server identity. Required; validated against nameRE.
	Name string
	// Dir is the parent directory the project directory is created under.
	// Empty means the current working directory.
	Dir string
	// ModulePath is the Go module path for the scaffolded project's go.mod.
	// Empty falls back to "example.com/<name>" — a placeholder a developer
	// renames; the scaffold compiles either way.
	ModulePath string
	// DockyardReplace, when non-empty, adds a `replace` directive to the
	// scaffolded go.mod pointing the Dockyard runtime import at a local
	// checkout. It is the pre-release workflow: until Dockyard is published to
	// a module registry, a scaffolded project cannot `go get` it, so the CLI
	// and the integration test set this to a local Dockyard path. A released
	// Dockyard leaves it empty and the scaffold depends on the published
	// module version directly.
	DockyardReplace string
	// DockyardWebPath is the web/ sibling of DockyardReplace — an absolute path
	// to the Dockyard checkout's web/ directory. Templates that depend on the
	// in-repo @dockyard/bridge and @dockyard/ui packages substitute it into
	// their package.json `file:` dependencies so a scaffolded project can
	// `npm install` before the packages are published to npm. Empty leaves
	// published-version fallbacks in place (post-publish workflow).
	DockyardWebPath string
	// ExampleToolTaskSupport sets the no-template scaffold's example tool's
	// task_support declaration. The zero value ("") preserves the historical
	// behaviour — the example tool ships as task_support: forbidden, a plain
	// synchronous tool. Setting it to manifest.TaskSupportOptional or
	// TaskSupportRequired makes the scaffold both (a) declare the example
	// tool that way in the rendered manifest and (b) emit the engine-wired
	// shape of main.go — a `tasks.NewInMemoryStore()` + `tasks.NewEngine(...)`
	// block + `server.Options{Tasks: engine}` (D-164).
	//
	// This is the manifest-side knob the scaffold consumes; RequiresTasksEngine
	// is the corresponding read side that `dockyard run` consults at start time
	// against the project's loaded manifest.
	ExampleToolTaskSupport manifest.TaskSupport

	// DockyardVersion is the version of the Dockyard runtime module to pin in
	// the scaffolded go.mod's require directive — normally the version of the
	// `dockyard` CLI doing the scaffolding (cli.ResolvedVersion()). When it is
	// a real release version (vX.Y.Z) the require pins it, so a project that
	// drops the local `replace` resolves the published module from the proxy
	// without a hand edit. An empty value or the dev placeholder leaves the
	// historical `v0.0.0` placeholder (only ever resolved through the replace
	// directive — the build-from-source path).
	DockyardVersion string

	// Here permits scaffolding into a target directory that already has
	// content (the `dockyard new --here` flag). With Here false (the
	// default) a non-empty target is refused with ErrTargetExists. With
	// Here true the existing content is left in place, but a scaffold output
	// that would overwrite an existing file is still refused with
	// ErrFileCollision — `dockyard new` never silently overwrites a file.
	Here bool
}

type PathSubstitution struct {
	From string
	To   string
}

type Registry struct {
	// contains filtered or unexported fields
}

type Result struct {
	// Dir is the project directory that was created.
	Dir string
	// Files is the project-relative path of every file written, sorted.
	Files []string
}

type Substitution struct {
	// From is the placeholder token a template author writes into the source
	// tree (e.g. "__PROJECT_NAME__"). Tokens are double-underscored on each
	// side so a real source line never accidentally collides with one.
	From string
	// To is the value the From token is replaced with — the user's choice
	// (the project name) or a derived value (the module path).
	To string
}

type Template interface {
	// Name is the wire name a developer passes to `dockyard new --template <name>`.
	// It matches the Registry key and is short, kebab-case.
	Name() string
	// Summary is one-line help text the CLI prints next to the template name.
	Summary() string
	// Materialise builds the project file set in memory, keyed by project-
	// relative path. The returned map is the entire scaffolded project — the
	// CLI writes it to disk verbatim. Identical Options must yield identical
	// bytes (the materialiser is deterministic — the golden test depends on it).
	Materialise(opts Options) (map[string][]byte, error)
}