project

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 11, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package project ties config, catalog, render, and manifest together to sync rendered files into a project and check them for drift.

Index

Constants

View Source 
const Version = "0.16.0"

Version is the awf release version — the single version authority (ADR-0049): gate comparisons, the lock stamp, the bootstrap pin, and the CLI output all read this const.

Variables

This section is empty.

Functions

func CatalogNames 

func CatalogNames(cat *catalog.Catalog, singular string) ([]string, bool)

CatalogNames returns the catalog pool for a singular CLI kind; ok is false for a kind with no catalog pool (domains).

func CollisionsAt added in v0.6.0 

func CollisionsAt(root string, planned []string) ([]string, error)

CollisionsAt filters planned project-relative paths to those that already exist under root and are not recorded in root's lock (not awf-managed). Split from InitCollisions so init's pre-prompt probe can plan outputs in a throwaway scaffold and test them against the real root; the ADR-0016 collision semantics are unchanged.

func DeriveDocTitle added in v0.15.0 

func DeriveDocTitle(name string) string

DeriveDocTitle turns a local doc name into a display title: the last path segment, hyphens to spaces, each word capitalized, empty words (from a trailing or double hyphen) dropped. "guides/release-steps" → "Release Steps". awf new doc seeds the sidecar with it, and synthesis falls back to it when the sidecar omits data.title.

func EnabledNames 

func EnabledNames(c *config.Config, singular string) ([]string, bool)

EnabledNames returns the config enable array for a singular CLI kind.

func HookNames added in v0.6.0 

func HookNames() []string

HookNames returns the git-hook payload names the hooks singleton renders (ADR-0048), for CLI surfaces that enumerate them (the KnownTargets pattern).

func Kinds 

func Kinds() []string

Kinds returns the singular CLI kind tokens in display order.

func KnownTargets added in v0.4.0 

func KnownTargets() []string

KnownTargets returns the known adapter names in sorted order. The bespoke `awf {enable,disable,list} target` path validates against this set (inv: target-cli). invariant: target-cli

func NeededVars added in v0.13.0 

func NeededVars(trim *config.CatalogTrim) (map[string]bool, error)

NeededVars returns the var names referenced by the templates the scaffolded enabled set will render: the enable arrays scaffoldSelection derives, the always-on singletons (agents-doc + plain), and the default-enabled hook payloads. Init's interactive path prompts only for these (ADR-0086 Decision 6); the scaffold still seeds the full catalog union as empty keys (ADR-0022 unchanged), and an explicit --set/answers value is honored regardless.

func PluralKind 

func PluralKind(singular string) (string, bool)

PluralKind maps a singular CLI kind token to its config enable-array key.

func PotentialVarConsumers added in v0.14.0 

func PotentialVarConsumers() (map[string][]string, error)

PotentialVarConsumers inverts the full catalog's raw template sources into var → sorted consumer labels: the dormant-hint side of the consumption graph (ADR-0088). Raw-source scanning is sound because no partial references .vars — guarded by a test beside the reference's goldens.

func ScaffoldConfig 

func ScaffoldConfig(prefix string, vars map[string]string, trim *config.CatalogTrim, scopes []string) ([]byte, []string, error)

ScaffoldConfig generates the bytes of a .awf/config.yaml that enables the workflow-core skills and docs (ADR-0022) and every agent in the embedded catalog (as flat name arrays), and pre-populates the vars block with the union of all {{ .vars.X }} names referenced by every catalog template. Each var is seeded with an empty string so that strict render (missingkey=zero + <no value> check) does not fail on sync, and so a later `awf enable` of an opt-in skill renders cleanly. It also seeds the self-pinning bootstrap (ADR-0040) and the git-hook payloads (ADR-0048) enabled by default, and writes a resolved commit-scope list to audit.allowedScopes (ADR-0051). The second return value lists the closure additions beyond a trim's explicit selection (kind-prefixed, e.g. "skill reviewing-plan-resync"), empty for the untrimmed default.

func ScaffoldVarRefs added in v0.14.0 

func ScaffoldVarRefs(kind string) ([]string, error)

ScaffoldVarRefs returns the vars referenced by the base template a new local artifact of kind ("skill"/"agent") renders from — `awf new`'s seeding surface (ADR-0087 Decision 4). Parts are raw (ADR-0034), so the base template is a local artifact's only var channel; today both bases are varless and this returns empty, but a future base gaining a var reference is seeded correct by construction.

func Uninstall 

func Uninstall(root string) (int, error)

Uninstall removes awf's generated footprint from root: every file recorded in the lock, the directories left empty by their removal, and the now-stale lock itself. It leaves the authored .awf/ config in place and returns the count of files removed. It is a free function (not a *Project method) so a broken config.yaml does not block uninstall — only the lock and root are needed. invariant: uninstall-removes-lock-tracked

Types

type ADRRef added in v0.16.0 

type ADRRef struct {
	Number     string   `json:"number"`
	Title      string   `json:"title"`
	Status     string   `json:"status"`
	Path       string   `json:"path"`
	Invariants []string `json:"invariants"`
}

ADRRef is an ADR related to the query via an owning domain. Title is the human title with the "ADR-NNNN: " prefix stripped (Number carries it). Invariants are the inv: slugs this ADR declares (its Invariants section), the ADR-side half of the backing-invariants join (ADR-0092 D4).

type Backup added in v0.3.0 

type Backup struct {
	Path  string // project-relative file that was overwritten
	Bak   string // project-relative backup copy (.awf-bak[.N])
	Index bool   // the file is the generated ADR/domain index (ownership-takeover note)
}

Backup records a foreign file preserved before sync overwrote its path.

type Change added in v0.13.0 

type Change struct {
	Path  string
	Cause string
}

Change records a sync-written file whose rendered output differs from the prior lock's, with the cause the lock's hashes can attribute: "template" (the upstream template source moved), "config" (the project's effective inputs — vars, sidecar, parts — moved), "template+config" (both), "internal" (hashes unmoved: a non-hashed input such as the binary's version stamp), "regenerated" (a generated index, which carries no hashes to attribute), or "added" (no prior entry). The provenance triage signal for reviewing a large sync diff — upstream churn vs the project's own inputs.

type ContextResult added in v0.16.0 

type ContextResult struct {
	Paths      []string    `json:"paths"`
	Domains    []DomainRef `json:"domains"`
	Invariants []string    `json:"invariants"`
	ADRs       []ADRRef    `json:"adrs"`
	Unowned    []string    `json:"unowned"`
}

ContextResult is the read-only context awf holds for a set of repo-relative paths: their owning domains (each with the rendered current-state pointer), the invariant slugs backed under those paths, the ADRs related via the owning domains, and any queried path matching no configured domain.

type DomainRef added in v0.16.0 

type DomainRef struct {
	Name         string `json:"name"`
	CurrentState string `json:"currentState"`
}

DomainRef is an owning domain and its rendered current-state doc path, derived by convention (never a sidecar field — ADR-0086).

type Layout 

type Layout struct {
	DocsDir    string
	ADRDir     string
	ActiveMd   string
	PlansDir   string
	Docs       map[string]string // name -> output path; present iff enabled (inv: layout-docs-enabled-only)
	DomainsDir string
}

Layout is the fixed, awf-given docs layout derived from cfg.DocsDir, in typed form for Go consumers. These paths are not configurable through vars. templateMap projects it into the .layout template namespace (templates read a map, not unexported struct fields) and into the per-file ConfigHash. The mandatory-singleton paths are not struct fields: they derive from the catalog doc collection in templateMap (ADR-0061).

type PlanOp added in v0.12.0 

type PlanOp struct {
	Node       catalog.Node
	Enable     bool
	RequiredBy string
}

PlanOp is one enable-array change in a resolver plan (ADR-0081 Decision 2). RequiredBy carries provenance: the artifact demanding the op ("" for the node the user named).

type Project 

type Project struct {
	Root    string
	Cfg     *config.Config
	Cat     *catalog.Catalog
	Targets []Target
	// contains filtered or unexported fields
}

func Open 

func Open(root string) (*Project, error)

func (*Project) AdvisoryNotes added in v0.10.0 

func (p *Project) AdvisoryNotes() ([]string, error)

AdvisoryNotes returns the non-failing render advisories in print order — the ADR-0045 unset-var notes, the ADR-0070 stub notes, then the ADR-0083 part- marker notes — computed from one RenderAll pass plus the domain-doc generation, which renders outside it.

func (*Project) Audit 

func (p *Project) Audit(baseOverride string) ([]audit.Finding, error)

Audit runs the process-conformance audit (ADR-0017) over the branch range. baseOverride wins over the configured base branch when non-empty.

func (*Project) BackupFile 

func (p *Project) BackupFile(rel string) (string, error)

BackupFile copies a colliding project-relative file to a free <path>.awf-bak[.N] sibling (never clobbering a prior backup) and returns the backup's project-relative path. invariant: init-force-backs-up

func (*Project) Check 

func (p *Project) Check() ([]manifest.Drift, error)

func (*Project) CheckInvariants 

func (p *Project) CheckInvariants() ([]invariants.Finding, error)

CheckInvariants reports Implemented-ADR invariant slugs that lack a backing `<marker> invariant: <slug>` comment (per the project's configured invariant sources) under the project root.

func (*Project) ConfigReferenceModel added in v0.14.0 

func (p *Project) ConfigReferenceModel() (map[string]any, error)

ConfigReferenceModel computes the reference's four collections (configKeys, varEntries, sidecarFields, dataKeys) with live project state — the `awf config` command's data source, sharing the doc's builder.

func (*Project) ContextFor added in v0.16.0 

func (p *Project) ContextFor(paths []string) (ContextResult, error)

ContextFor assembles the read-only context for paths. It reads only committed state (domain sidecars, ADR files, source markers) and writes nothing.

func (*Project) InitCollisions 

func (p *Project) InitCollisions() ([]string, error)

InitCollisions returns planned output paths that already exist on disk and are not recorded in the prior lock (i.e. not awf-managed). An awf-managed path that already exists is not a collision — re-init is idempotent.

func (*Project) NewADR added in v0.6.0 

func (p *Project) NewADR(title string) (string, error)

NewADR scaffolds a new ADR file under the project's decisions dir: the next sequential number, the rendered template with its title/date filled in and marker comments stripped, refusing to overwrite an existing file. Mirrors the CheckInvariants/Audit pattern — cmd/awf reaches this only through this exported method, never internal/project.Layout directly.

func (*Project) PlannedOutputs 

func (p *Project) PlannedOutputs() ([]string, error)

PlannedOutputs returns the project-relative paths Sync would write: every RenderAll output plus the generated ACTIVE.md, domain docs, and config reference. Used by awf init to detect collisions before writing (ADR-0016).

func (*Project) RenderAll 

func (p *Project) RenderAll() ([]RenderedFile, error)

func (*Project) ResolveDisable added in v0.16.0 

func (p *Project) ResolveDisable(kind, name string) []PlanOp

ResolveDisable plans disabling (kind, name): the node plus every enabled, non-local artifact that transitively requires it (reverse closure, fixed point over direct edges). Local-sidecar artifacts have no catalog edges demanded of them, mirroring the validator's skip. invariant: remove-refuses-dependents

func (*Project) ResolveEnable added in v0.16.0 

func (p *Project) ResolveEnable(kind, name string) []PlanOp

ResolveEnable plans enabling (kind, name): the node plus its missing forward closure. An already-enabled dependency is skipped along with its subtree — the open-time validation invariant guarantees enabled implies closed. invariant: add-applies-closure-plan

func (*Project) SyncReport added in v0.3.0 

func (p *Project) SyncReport() ([]Backup, []Change, []string, error)

SyncReport renders and writes the project, additionally backing up any foreign file (on disk but absent from the start-of-sync lock) before overwriting it, and returning those backups (ADR-0035) plus the per-file provenance of output that changed against the prior lock and the lock-relative paths of the files its prune actually removed (both path-sorted; a file whose output is byte-identical, and a first sync with no prior lock, report no change — a routine re-sync stays silent).

type RenderedFile 

type RenderedFile struct {
	Path         string
	Content      string
	TemplateID   string
	TemplateHash string
	ConfigHash   string
	// contains filtered or unexported fields
}

type Target 

type Target struct {
	Name       string
	SkillDir   string // dir holding rendered skills, e.g. ".claude/skills"
	AgentDir   string // dir holding rendered agents, e.g. ".claude/agents"
	BridgeFile string // adapter bridge file at repo root, "" if none
}

Target places adapter (tool-specific) artifacts for one runtime. Neutral artifacts (AGENTS.md, docs, domains) are not target-scoped (ADR-0016).

func (Target) AgentPath 

func (t Target) AgentPath(name string) string

AgentPath is the output path for a rendered agent under this target.

func (Target) SkillPath 

func (t Target) SkillPath(prefix, name string) string

SkillPath is the output path for a rendered skill under this target.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.