project

package
v0.14.1 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2026 License: MIT Imports: 25 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.14.1"

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 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 {add,remove,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 add` 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 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 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
	Add        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) 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) ResolveAdd added in v0.12.0 

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

ResolveAdd 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) ResolveRemove added in v0.12.0 

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

ResolveRemove 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) 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.