Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -95,10 +95,12 @@ tmp
.zed/settings.json
/.devenv*
/.devenv-root
/.envrc.local
/.stack/state
/devshell
/packages/gen/infra/package.json.backup
/packages/infra/package.json.backup
/process-compose.yaml
/result
apps/stackpanel-go/.stack/keys/
build
Expand All @@ -108,7 +110,6 @@ dist
logs
node_modules
packages/scripts/entrypoints/
process-compose.yaml
temp
tmp
# ── END stackpanel ──
Expand Down
11 changes: 5 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ You are an experienced, pragmatic software engineering AI agent. Do not over-eng
├── .stack/
│ ├── config.nix # Primary user config (apps, services, theme, IDE)
│ ├── data/*.nix # Auto-loaded data tables
│ ├── gen/ # Generated files (checked in; regenerated on devshell entry)
│ ├── gen/ # Ephemeral generated files (gitignored; regenerated on devshell entry)
│ ├── secrets/ # SOPS config + encrypted YAML secrets
│ └── state/ # Runtime state (gitignored: stack.json, keys/, etc.)
├── tests/ # Smoke tests + template tests
Expand Down Expand Up @@ -213,13 +213,12 @@ config = lib.mkIf cfg.enable {
};
```

### Adding Generated Files (CLI-based generation)
### Adding Generated Files (`stackpanel.files.entries`)

**Do not** use `devenv.files` for generated files — the Go CLI is the single writer (avoids symlink issues).
Declare generated files via `stackpanel.files.entries.<path>` in the owning Nix module:

1. Add the data to `fullConfig` in the relevant Nix module
2. Add generation logic in `apps/stackpanel-go/internal/generator/`
3. Check generated output into `.stack/gen/` for IDE support without devshell
1. Set `format` (`"text"`, `"json"`, `"yaml"`, `"toml"`, `"lines"`, `"derivation"`, `"symlink"`), `writer` (`"full"`, `"block"`, `"paths"`), and `adopt` (`"none"`, `"backup"`, `"refuse"`).
2. Set `gitignore = true` when the file is ephemeral/machine-local (automatically added to the managed `.gitignore` block and checked by `stack doctor`); defaults to `true` for symlinks and paths under `.stack/{gen,profile,state,keys,bin}/` or `.tasks/`, and `false` (committed) for workspace/repo files like `packages/gen/*`.

### Proto-Nix Schema System

Expand Down
14 changes: 14 additions & 0 deletions apps/stackpanel-go/internal/agent/server/nix_files.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ import (
type GeneratedFile struct {
Path string `json:"path"`
Type string `json:"type"`
Writer string `json:"writer,omitempty"`
Gitignore bool `json:"gitignore"`
Mode *string `json:"mode,omitempty"`
Source *string `json:"source,omitempty"`
Description *string `json:"description,omitempty"`
Expand Down Expand Up @@ -55,6 +57,8 @@ type nixFilesOutput struct {
type nixFileEntry struct {
Path string `json:"path"`
Type string `json:"type"`
Writer string `json:"writer"`
Gitignore bool `json:"gitignore"`
Mode *string `json:"mode"`
Source *string `json:"source"`
Description *string `json:"description"`
Expand Down Expand Up @@ -129,6 +133,8 @@ let
in {
inherit path;
type = entryType;
writer = entry.writer or "full";
gitignore = entry.gitignore or false;
mode = entry.mode or null;
source = entry.source or null;
description = entry.description or null;
Expand All @@ -144,6 +150,8 @@ let
} else {
inherit path;
type = "text";
writer = "full";
gitignore = false;
mode = null;
source = null;
description = null;
Expand Down Expand Up @@ -218,6 +226,8 @@ let
in {
inherit path;
type = entryType;
writer = entry.writer or "full";
gitignore = entry.gitignore or false;
mode = entry.mode or null;
source = entry.source or null;
description = entry.description or null;
Expand All @@ -231,6 +241,8 @@ let
} else {
inherit path;
type = "text";
writer = "full";
gitignore = false;
mode = null;
source = null;
description = null;
Expand Down Expand Up @@ -288,6 +300,8 @@ func (s *Server) buildFilesResponse(data *nixFilesOutput) *GeneratedFilesRespons
file := GeneratedFile{
Path: path,
Type: entry.Type,
Writer: entry.Writer,
Gitignore: entry.Gitignore,
Mode: entry.Mode,
Source: entry.Source,
Description: entry.Description,
Expand Down
5 changes: 3 additions & 2 deletions apps/stackpanel-go/internal/fileops/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,9 @@ type Entry struct {
StorePath string `json:"storePath,omitempty"`
BlockLabel string `json:"blockLabel,omitempty"`
CommentPrefix string `json:"commentPrefix,omitempty"`
Mode string `json:"mode,omitempty"` // octal string, e.g. "0755"
Adopt string `json:"adopt,omitempty"` // "none" | "backup" | "refuse"
Mode string `json:"mode,omitempty"` // octal string, e.g. "0755"
Adopt string `json:"adopt,omitempty"` // "none" | "backup" | "refuse"
Gitignore bool `json:"gitignore,omitempty"` // true when ephemeral/machine-local
Ops []JSONOp `json:"ops,omitempty"`
Collisions []Collision `json:"collisions,omitempty"`
}
Expand Down
1 change: 1 addition & 0 deletions apps/stackpanel-go/internal/reconcile/plan.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ type PlanEntry struct {
Format string `json:"format"`
Writer string `json:"writer"`
Adopt string `json:"adopt"`
Gitignore bool `json:"gitignore"`
Mode *string `json:"mode"`
BlockLabel string `json:"blockLabel"`
CommentPrefix string `json:"commentPrefix"`
Expand Down
5 changes: 5 additions & 0 deletions apps/stackpanel-go/internal/reconcile/rc_fileops.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,16 @@ func (r *FileopsReconciler) Diagnose(ctx *Context) (*Diagnosis, error) {
}, nil
}
diag := &Diagnosis{}
var gitignoredPaths []string
for _, entry := range manifest.Files {
if entry.Gitignore {
gitignoredPaths = append(gitignoredPaths, entry.Path)
}
for _, c := range entry.Collisions {
diag.Findings = append(diag.Findings, collisionFinding(fileopsID, entry.Path, c))
}
}
diag.Findings = append(diag.Findings, checkGitignoredNotTracked(ctx, fileopsID, gitignoredPaths)...)
summary, err := fileops.PlanManifest(ctx.ProjectRoot, ctx.StateDir, *manifest)
if err != nil {
return nil, err
Expand Down
48 changes: 45 additions & 3 deletions apps/stackpanel-go/internal/reconcile/rc_files.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,10 @@ type manifestFile struct {
}

type manifestEntry struct {
Path string `json:"path"`
Format string `json:"format"`
Writer string `json:"writer"`
Path string `json:"path"`
Format string `json:"format"`
Writer string `json:"writer"`
Gitignore bool `json:"gitignore"`
// Managed is only present in manifests written before the writer axis
// existed; it is read so a pre-upgrade generation's stale blocks are still
// stripped rather than deleted as whole files.
Expand Down Expand Up @@ -87,11 +88,15 @@ func (r *FilesReconciler) Diagnose(ctx *Context) (*Diagnosis, error) {

diag := &Diagnosis{}
currentPaths := map[string]bool{}
var gitignoredPaths []string
entries := append([]manifestEntry{}, current.Files...)
sort.Slice(entries, func(i, j int) bool { return entries[i].Path < entries[j].Path })

for _, e := range entries {
currentPaths[e.Path] = true
if e.Gitignore {
gitignoredPaths = append(gitignoredPaths, e.Path)
}
abs := filepath.Join(ctx.ProjectRoot, e.Path)
summary := ""
if e.Source != nil && *e.Source != "" {
Expand Down Expand Up @@ -204,9 +209,46 @@ func (r *FilesReconciler) Diagnose(ctx *Context) (*Diagnosis, error) {
diag.Notes = append(diag.Notes, "previous manifest unreadable: "+err.Error())
}

diag.Findings = append(diag.Findings, checkGitignoredNotTracked(ctx, filesID, gitignoredPaths)...)

return diag, nil
}

// checkGitignoredNotTracked warns when a generated file marked gitignore = true
// in the manifest is currently tracked in the git index.
func checkGitignoredNotTracked(ctx *Context, reconcilerID string, paths []string) []Finding {
if len(paths) == 0 || ctx == nil || ctx.ProjectRoot == "" {
return nil
}
if _, err := os.Stat(filepath.Join(ctx.ProjectRoot, ".git")); err != nil {
return nil
}
args := append([]string{"-C", ctx.ProjectRoot, "ls-files", "-z", "--"}, paths...)
cmd := exec.Command("git", args...)
if ctx.Ctx != nil {
cmd = exec.CommandContext(ctx.Ctx, "git", args...)
}
out, err := cmd.Output()
if err != nil || len(out) == 0 {
return nil
}
var findings []Finding
for _, tracked := range strings.Split(strings.TrimRight(string(out), "\x00"), "\x00") {
if tracked == "" {
continue
}
findings = append(findings, Finding{
Reconciler: reconcilerID,
ID: "gitignore-tracked:" + tracked,
Severity: SeverityWarning,
Title: "ephemeral generated file is tracked by git (gitignore = true)",
Path: tracked,
FixCommand: "git rm --cached " + tracked,
})
}
return findings
}

// Apply implements Reconciler by running the generation's write-files script.
func (r *FilesReconciler) Apply(ctx *Context) (*ApplyResult, error) {
if ctx.Getenv("STACKPANEL_FILES_MANIFEST") == "" {
Expand Down
65 changes: 65 additions & 0 deletions apps/stackpanel-go/internal/reconcile/reconcile_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@ package reconcile

import (
"bytes"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
Expand Down Expand Up @@ -440,3 +442,66 @@ func TestScaffoldSkipsExistingProjectWithoutFetching(t *testing.T) {
t.Errorf("expected nothing written, got %+v", res.Applied)
}
}

func TestFilesReconcilerWarnsWhenGitignoredEntryIsTracked(t *testing.T) {
t.Parallel()

root := t.TempDir()
storeFile := filepath.Join(t.TempDir(), "store-file")
if err := os.WriteFile(storeFile, []byte("ok\n"), 0o644); err != nil {
t.Fatal(err)
}
for _, rel := range []string{"ephemeral.sh", "committed.json", "untracked-ephemeral.sh"} {
if err := os.WriteFile(filepath.Join(root, rel), []byte("ok\n"), 0o644); err != nil {
t.Fatal(err)
}
}

gitRun := func(args ...string) {
t.Helper()
cmd := exec.Command("git", append([]string{"-C", root}, args...)...)
cmd.Env = append(os.Environ(), "GIT_CONFIG_GLOBAL=/dev/null", "GIT_CONFIG_NOSYSTEM=1")
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("git %v: %v\n%s", args, err, out)
}
}
gitRun("init", "-q")
gitRun("add", "ephemeral.sh", "committed.json")

manifestPath := filepath.Join(t.TempDir(), "files.json")
manifestJSON := fmt.Sprintf(`{
"version": 2,
"files": [
{"path": "ephemeral.sh", "format": "text", "writer": "full", "gitignore": true, "storePath": %q},
{"path": "committed.json", "format": "json", "writer": "full", "gitignore": false, "storePath": %q},
{"path": "untracked-ephemeral.sh", "format": "text", "writer": "full", "gitignore": true, "storePath": %q}
]
}`, storeFile, storeFile, storeFile)
if err := os.WriteFile(manifestPath, []byte(manifestJSON), 0o644); err != nil {
t.Fatal(err)
}

ctx := &Context{
Ctx: t.Context(),
ProjectRoot: root,
StateDir: filepath.Join(root, ".stack", "profile"),
Getenv: func(k string) string {
if k == "STACKPANEL_FILES_MANIFEST" {
return manifestPath
}
return ""
},
}
rc := &FilesReconciler{}
diag, err := rc.Diagnose(ctx)
if err != nil {
t.Fatal(err)
}
if len(diag.Findings) != 1 {
t.Fatalf("expected 1 finding for tracked gitignore=true file, got %+v", diag.Findings)
}
got := diag.Findings[0]
if got.Path != "ephemeral.sh" || got.FixCommand != "git rm --cached ephemeral.sh" || got.Severity != SeverityWarning {
t.Errorf("unexpected finding: %+v", got)
}
}
Loading
Loading