file

func Chmod ¶ added in v0.2.0

func Chmod(name string, perm os.FileMode) error

Chmod sets a file's mode. On every real build target this is just os.Chmod; it is a package function (rather than a direct os.Chmod at each call site) only so the wasm build - TinyGo's js/wasm os package has no Chmod - can substitute a no-op (see chmod_wasm.go). Packages that compile into the Buzz playground wasm (internal/file itself, internal/cache) call this instead of os.Chmod so the undefined symbol disappears from that build, not merely goes uncalled.

func NormalizeWorkspacePath ¶ added in v0.4.0

func NormalizeWorkspacePath(input, root string) (string, bool)

NormalizeWorkspacePath canonicalises a path-SHAPED string to the workspace-relative, forward-slash form magus names files by, so the spellings a human actually produces - shell tab-completion's "./a/b", an editor's "Copy Path" absolute, a Windows-side agent's "a\b" - all name what a bare "a/b" names.

ok is false when input is not path-shaped, or when it is a path that cannot be placed inside root; the returned string is then input, unchanged. Leaving it alone is the point: a path from a different checkout that was rewritten into a plausible relative path would name a DIFFERENT file, which is worse than finding nothing.

Path-shaped means a separator or a drive letter. A bare term ("guard_shell.go", "hint") is never touched, and neither is anything holding "://" - path.Clean collapses a URL's double slash.

A leading "/" that is not a real path under root is read as anchored AT the workspace root, but only when that reading names something that exists; likewise the backslash translation. root may be empty, which limits this to the shapes needing no workspace on disk (dot-relative and interior "..").

func ResolveDependsOn ¶ added in v0.4.0

func ResolveDependsOn(input, anchor string) (string, error)

ResolveDependsOn canonicalises a project path hand-written in a magusfile's depends_on list. Both spellings are a deliberate affordance for a human author: repo-relative ("libs/foo") and dot-relative ("../foo") both work.

This is the one surface that wants that ambiguity. A path produced by magus itself - a project import, a CLI reference - has exactly one correct reading and uses the entry point named for it.

func ResolveImport ¶ added in v0.4.0

func ResolveImport(input, anchor string) (string, error)

ResolveImport canonicalises a path relative to the importing magusfile's directory: the path written in an `import "project/<path>"`, or that path with a file suffix appended (what the `.file(rel)` member passes).

It always anchors, which is what makes it its own entry point rather than a call to resolveAmbiguous. That two-mode reading takes a BARE input as workspace-relative and so silently mis-anchors the common descendant form; an import path has no such mode, because the module loader has always resolved it against the importing file's directory, so a bare "guides/agents" imported from docs/ means docs/guides/agents and never a top-level guides/agents.

func ResolveProject ¶ added in v0.4.0

func ResolveProject(ctx context.Context, input, anchor string) (string, error)

ResolveProject canonicalises a project reference to a workspace-relative, forward-slash path.

A plain "<path>" is the canonical spelling. The "" and "/" all-projects sentinels pass through untouched for the caller to fan out. Everything else takes the same ambiguous reading as ResolveDependsOn: dot-relative against anchor, bare paths workspace-relative, absolute or escaping paths rejected.

The retired "workspace://<path>" form still parses, with a warning; a bare "workspace://" is still the root alias.

This is the one place a CLI-supplied project reference is normalized; add new rules for that surface here rather than in callers. It is not the only entry point: an `import "project/<path>"` path anchors unconditionally and goes through ResolveImport instead.

func WriteFileAtomic ¶

func WriteFileAtomic(path string, data []byte, perm os.FileMode) error

WriteFileAtomic writes data to path via a same-directory temp file + rename. The temp file is fsync'd before rename; readers never see a partial file.