go.step.sm/cli-utils v0.9.0: manage configuration files using fileutil WriteSnippet, AppendNewLine, PrependLine, and RemoveLine

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: manage configuration files using fileutil WriteSnippet, AppendNewLine, PrependLine, and RemoveLine
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.step.sm/cli-utils@v0.9.0
Demonstrate these symbols/APIs:
  - go.step.sm/cli-utils/fileutil.AppendNewLine
  - go.step.sm/cli-utils/fileutil.PrependLine
  - go.step.sm/cli-utils/fileutil.RemoveLine
  - go.step.sm/cli-utils/fileutil.WriteSnippet
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:c446c16471869f1d6b8cd0aaf5dcd3539153027512f437256c7b0457483d6171","contract":["WriteSnippet creates a header-and-footer bounded snippet in a new file","WriteSnippet replaces an existing snippet while preserving surrounding content","AppendNewLine appends content and ensures newline separation","PrependLine inserts a line at the top and removes duplicates with the same prefix","RemoveLine deletes the line matching a substring from the configuration file"],"goal":"manage configuration files using fileutil WriteSnippet, AppendNewLine, PrependLine, and RemoveLine","kind":"HOW","packages":["pkg:golang/go.step.sm/cli-utils@v0.9.0"],"schemaVersion":1,"symbols":["go.step.sm/cli-utils/fileutil.AppendNewLine","go.step.sm/cli-utils/fileutil.PrependLine","go.step.sm/cli-utils/fileutil.RemoveLine","go.step.sm/cli-utils/fileutil.WriteSnippet"]},"contractCommand":["go","test","./..."],"environment":{"arch":"amd64","distro":"ubuntu","ecosystem":"golang","language":"go","languageVersion":"1.26","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.step.sm/cli-utils@v0.9.0"],"schemaVersion":1,"subject":"pkg:golang/go.step.sm/cli-utils@v0.9.0","symbols":["go.step.sm/cli-utils/fileutil.AppendNewLine","go.step.sm/cli-utils/fileutil.PrependLine","go.step.sm/cli-utils/fileutil.RemoveLine","go.step.sm/cli-utils/fileutil.WriteSnippet"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require go.step.sm/cli-utils v0.9.0

require (
	github.com/chzyer/readline v1.5.1 // indirect
	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
	github.com/manifoldco/promptui v0.9.0 // indirect
	github.com/mattn/go-colorable v0.1.4 // indirect
	github.com/mattn/go-isatty v0.0.11 // indirect
	github.com/mgutz/ansi v0.0.0-20200706080929-d51e80ef957d // indirect
	github.com/pkg/errors v0.9.1 // indirect
	github.com/russross/blackfriday/v2 v2.1.0 // indirect
	github.com/shurcooL/sanitized_anchor_name v1.0.0 // indirect
	github.com/urfave/cli v1.22.14 // indirect
	go.step.sm/crypto v0.43.1 // indirect
	golang.org/x/net v0.21.0 // indirect
	golang.org/x/sys v0.18.0 // indirect
)

github.com/BurntSushi/toml v1.3.2/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbicEuybxQ=
github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
github.com/chzyer/logex v1.2.1 h1:XHDu3E6q+gdHgsdTPH6ImJMIp436vR6MPtH8gP05QzM=
github.com/chzyer/logex v1.2.1/go.mod h1:JLbx6lG2kDbNRFnfkgvh4eRJRPX1QCoOIWomwysCBrQ=
github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
github.com/chzyer/readline v1.5.1 h1:upd/6fQk4src78LMRzh5vItIt361/o4uq553V8B5sGI=
github.com/chzyer/readline v1.5.1/go.mod h1:Eh+b79XXUwfKfcPLepksvw2tcLE/Ct21YObkaSkeBlk=
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/manifoldco/promptui v0.9.0 h1:3V4HzJk1TtXW1MTZMP7mdlwbBpIinw3HztaIlYthEiA=
github.com/manifoldco/promptui v0.9.0/go.mod h1:ka04sppxSGFAtxX0qhlYQjISsg9mR4GWtQEhdbn6Pgg=
github.com/mattn/go-colorable v0.1.4 h1:snbPLB8fVfU9iwbbo30TPtbLRzwWu6aJS6Xh4eaaviA=
github.com/mattn/go-colorable v0.1.4/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
github.com/mattn/go-isatty v0.0.8/go.mod h1:Iq45c/XA43vh69/j3iqttzPXn0bhXyGjM0Hdxcsrc5s=
github.com/mattn/go-isatty v0.0.11 h1:FxPOTFNqGkuDUGi3H/qkUbQO4ZiBa2brKq5r0l8TGeM=
github.com/mattn/go-isatty v0.0.11/go.mod h1:PhnuNfih5lzO57/f3n+odYbM4JtupLOxQOAqxQCu2WE=
github.com/mgutz/ansi v0.0.0-20200706080929-d51e80ef957d h1:5PJl274Y63IEHC+7izoQE9x6ikvDFZS2mDVS3drnohI=
github.com/mgutz/ansi v0.0.0-20200706080929-d51e80ef957d/go.mod h1:01TrycV0kFyexm33Z7vhZRXopbI8J3TDReVlkTgMUxE=
github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo=
github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
github.com/smallstep/assert v0.0.0-20200723003110-82e2b9b3b262 h1:unQFBIznI+VYD1/1fApl1A+9VcBk+9dcqGfnePY87LY=
github.com/smallstep/assert v0.0.0-20200723003110-82e2b9b3b262/go.mod h1:MyOHs9Po2fbM1LHej6sBUT8ozbxmMOFG+E+rx/GSGuc=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
github.com/urfave/cli v1.22.14 h1:ebbhrRiGK2i4naQJr+1Xj92HXZCrK7MsyTS/ob3HnAk=
github.com/urfave/cli v1.22.14/go.mod h1:X0eDS6pD6Exaclxm99NJ3FiCDRED7vIHpx2mDOHLvkA=
go.step.sm/cli-utils v0.9.0 h1:55jYcsQbnArNqepZyAwcato6Zy2MoZDRkWW+jF+aPfQ=
go.step.sm/cli-utils v0.9.0/go.mod h1:Y/CRoWl1FVR9j+7PnAewufAwKmBOTzR6l9+7EYGAnp8=
go.step.sm/crypto v0.43.1 h1:18Z/M49SnFDPXvFbfoN/ugE1i0J7phLWARhSQs/XSDI=
go.step.sm/crypto v0.43.1/go.mod h1:9n90D/SWjH1hTyQn1hgviUGyK8YRv743S8UZHYbt4BU=
golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4=
golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
golang.org/x/sys v0.0.0-20181122145206-62eef0e2fa9b/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package sample

import (
	"os"

	"go.step.sm/cli-utils/fileutil"
)

// AddConfigSnippet adds or updates a managed snippet in a config file.
func AddConfigSnippet(filename string, snippet string, perm os.FileMode) error {
	return fileutil.WriteSnippet(filename, []byte(snippet), perm)
}

// AppendConfigDirective appends a directive line to a config file with newline handling.
func AppendConfigDirective(filename string, directive string, perm os.FileMode) error {
	return fileutil.AppendNewLine(filename, []byte(directive), perm)
}

// PrependUniqueConfigDirective prepends a directive line and removes older duplicates.
func PrependUniqueConfigDirective(filename string, directive string, perm os.FileMode) error {
	return fileutil.PrependLine(filename, []byte(directive), perm)
}

// RemoveConfigDirective removes a line matching the given substring from a config file.
func RemoveConfigDirective(filename, substr string) error {
	return fileutil.RemoveLine(filename, substr)
}

{
  "schemaVersion": 1,
  "goal": "manage configuration files using fileutil WriteSnippet, AppendNewLine, PrependLine, and RemoveLine",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.step.sm/cli-utils@v0.9.0"
  ],
  "symbols": [
    "go.step.sm/cli-utils/fileutil.AppendNewLine",
    "go.step.sm/cli-utils/fileutil.PrependLine",
    "go.step.sm/cli-utils/fileutil.RemoveLine",
    "go.step.sm/cli-utils/fileutil.WriteSnippet"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

package test

import (
	"os"
	"path/filepath"
	"strings"
	"testing"

	"go.step.sm/cli-utils/fileutil"
)

func TestContract_WriteSnippet_NewFile(t *testing.T) {
	tmpDir := t.TempDir()
	filePath := filepath.Join(tmpDir, "config.conf")

	snippet := "setting_a = true\nsetting_b = 42"
	err := fileutil.WriteSnippet(filePath, []byte(snippet), 0600)
	if err != nil {
		t.Fatalf("WriteSnippet failed: %v", err)
	}

	content, err := os.ReadFile(filePath)
	if err != nil {
		t.Fatalf("failed to read file: %v", err)
	}

	contentStr := string(content)
	if !strings.Contains(contentStr, fileutil.SnippetHeader) {
		t.Errorf("expected snippet header %q in content; got %s", fileutil.SnippetHeader, contentStr)
	}
	if !strings.Contains(contentStr, fileutil.SnippetFooter) {
		t.Errorf("expected snippet footer %q in content; got %s", fileutil.SnippetFooter, contentStr)
	}
	if !strings.Contains(contentStr, "setting_a = true") || !strings.Contains(contentStr, "setting_b = 42") {
		t.Errorf("expected snippet body in content; got %s", contentStr)
	}
}

func TestContract_WriteSnippet_ReplaceExisting(t *testing.T) {
	tmpDir := t.TempDir()
	filePath := filepath.Join(tmpDir, "config.conf")

	initial := "# User header config\nhost = localhost\n"
	if err := os.WriteFile(filePath, []byte(initial), 0600); err != nil {
		t.Fatalf("failed to write initial file: %v", err)
	}

	firstSnippet := "managed_val = 1"
	if err := fileutil.WriteSnippet(filePath, []byte(firstSnippet), 0600); err != nil {
		t.Fatalf("first WriteSnippet failed: %v", err)
	}

	if err := fileutil.AppendNewLine(filePath, []byte("footer_directive = true"), 0600); err != nil {
		t.Fatalf("AppendNewLine failed: %v", err)
	}

	secondSnippet := "managed_val = 2\nmanaged_feature = on"
	if err := fileutil.WriteSnippet(filePath, []byte(secondSnippet), 0600); err != nil {
		t.Fatalf("second WriteSnippet failed: %v", err)
	}

	content, err := os.ReadFile(filePath)
	if err != nil {
		t.Fatalf("failed to read file: %v", err)
	}

	contentStr := string(content)
	if !strings.Contains(contentStr, "host = localhost") {
		t.Errorf("expected original header to be preserved; got %s", contentStr)
	}
	if !strings.Contains(contentStr, "footer_directive = true") {
		t.Errorf("expected footer to be preserved; got %s", contentStr)
	}
	if !strings.Contains(contentStr, "managed_val = 2") {
		t.Errorf("expected updated snippet; got %s", contentStr)
	}
	if strings.Contains(contentStr, "managed_val = 1") {
		t.Errorf("expected old snippet to be replaced; got %s", contentStr)
	}
}

func TestContract_AppendNewLine(t *testing.T) {
	tmpDir := t.TempDir()
	filePath := filepath.Join(tmpDir, "app.env")

	if err := os.WriteFile(filePath, []byte("KEY_ONE=val1"), 0600); err != nil {
		t.Fatalf("failed to write initial: %v", err)
	}

	if err := fileutil.AppendNewLine(filePath, []byte("KEY_TWO=val2"), 0600); err != nil {
		t.Fatalf("AppendNewLine failed: %v", err)
	}

	content, err := os.ReadFile(filePath)
	if err != nil {
		t.Fatalf("failed to read file: %v", err)
	}

	expected := "KEY_ONE=val1\nKEY_TWO=val2"
	if string(content) != expected {
		t.Errorf("expected %q, got %q", expected, string(content))
	}
}

func TestContract_PrependLine(t *testing.T) {
	tmpDir := t.TempDir()
	filePath := filepath.Join(tmpDir, "routes.conf")

	initial := "export PATH=/bin\nexport FOO=bar\nexport PATH=/bin\n"
	if err := os.WriteFile(filePath, []byte(initial), 0600); err != nil {
		t.Fatalf("failed to write initial: %v", err)
	}

	newLine := "export PATH=/bin"
	if err := fileutil.PrependLine(filePath, []byte(newLine), 0600); err != nil {
		t.Fatalf("PrependLine failed: %v", err)
	}

	content, err := os.ReadFile(filePath)
	if err != nil {
		t.Fatalf("failed to read file: %v", err)
	}

	lines := strings.Split(strings.TrimSpace(string(content)), "\n")
	if len(lines) != 2 {
		t.Fatalf("expected 2 lines after deduplication, got %d; content is %s", len(lines), string(content))
	}
	if lines[0] != newLine {
		t.Errorf("expected first line to be %q, got %q", newLine, lines[0])
	}
	if lines[1] != "export FOO=bar" {
		t.Errorf("expected second line to be %q, got %q", "export FOO=bar", lines[1])
	}
}

func TestContract_RemoveLine(t *testing.T) {
	tmpDir := t.TempDir()
	filePath := filepath.Join(tmpDir, "hosts.allow")

	initial := "192.168.1.10\n10.0.0.5\n172.16.0.2\n"
	if err := os.WriteFile(filePath, []byte(initial), 0600); err != nil {
		t.Fatalf("failed to write initial: %v", err)
	}

	if err := fileutil.RemoveLine(filePath, "10.0.0.5"); err != nil {
		t.Fatalf("RemoveLine failed: %v", err)
	}

	content, err := os.ReadFile(filePath)
	if err != nil {
		t.Fatalf("failed to read file: %v", err)
	}

	contentStr := string(content)
	if strings.Contains(contentStr, "10.0.0.5") {
		t.Errorf("expected 10.0.0.5 to be removed; got %s", contentStr)
	}
	if !strings.Contains(contentStr, "192.168.1.10") || !strings.Contains(contentStr, "172.16.0.2") {
		t.Errorf("expected other entries to remain; got %s", contentStr)
	}
}