scrub consumer-specific references (coily/coilysiren) so the library is fully generic #49

New issue

Closed

opened 2026-06-03 10:01:45 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-06-03 10:01:45 +00:00

Owner

Goal

cli-guard is the generic security-boundary framework: "every package must be importable from a different binary without consumer-specific types or defaults leaking in" (AGENTS.md). The code mostly honors that for types, but comments, test fixtures, and rationale refs are saturated with one consumer's name (coily) and its issue tracker (coilysiren/coily#N). Scrub all of it so the library reads as company-agnostic and mentions nothing specific to a single consumer.

Audit (grep, go + md, excluding the repo's own module path)

99 files contain coily / coilysiren / coilyco-bridge references.
86 consumer issue-refs in comments: coily#144, coilysiren/coily#270, https://github.com/coilysiren/coily/issues/136, etc.
384 bare coily word mentions in comments/code ("coily does X", "the way coily ...").
Test fixtures use coilysiren/coily as the sample owner/repo (e.g. dispatch/dispatch_test.go).

Plan

Comments: coily -> "the consumer" / "a consumer"; drop consumer issue-refs, or map to a cli-guard issue where an equivalent exists, else keep the rationale in generic wording.
Test fixtures: neutral sample identifiers (example-org/example-repo, primary/sib-a), so tests assert behavior, not a consumer's repo names.
AGENTS.md / README / examples: generic framing; example apps named for the primitive they demo, not a consumer.
Keep: the repo's own hosting module path forgejo.coilysiren.me/coilyco-flight-deck/cli-guard (its identity, not a consumer reference).

Acceptance

grep -rE 'coilysiren|\bcoily\b|coilyco-bridge' over *.go/*.md returns only the self module path.
make build / make test / make vet green; godoc pin regenerated for any changed exported doc comment.
Large mechanical diff: land in a branch for review.

Why

The fleet now spans multiple consumers (coily, ward, o2r, ...). A framework that narrates itself in one consumer's terms is harder for the others to adopt and reads as proprietary. Generic-by-default is the contract this repo already claims.

## Goal cli-guard is the generic security-boundary framework: "every package must be importable from a different binary without consumer-specific types or defaults leaking in" (AGENTS.md). The code mostly honors that for *types*, but comments, test fixtures, and rationale refs are saturated with one consumer's name (`coily`) and its issue tracker (`coilysiren/coily#N`). Scrub all of it so the library reads as company-agnostic and mentions nothing specific to a single consumer. ## Audit (grep, go + md, excluding the repo's own module path) - **99 files** contain `coily` / `coilysiren` / `coilyco-bridge` references. - **86** consumer issue-refs in comments: `coily#144`, `coilysiren/coily#270`, `https://github.com/coilysiren/coily/issues/136`, etc. - **384** bare `coily` word mentions in comments/code ("coily does X", "the way coily ..."). - Test fixtures use `coilysiren/coily` as the sample owner/repo (e.g. `dispatch/dispatch_test.go`). ## Plan 1. **Comments**: `coily` -> "the consumer" / "a consumer"; drop consumer issue-refs, or map to a cli-guard issue where an equivalent exists, else keep the rationale in generic wording. 2. **Test fixtures**: neutral sample identifiers (`example-org/example-repo`, `primary`/`sib-a`), so tests assert behavior, not a consumer's repo names. 3. **AGENTS.md / README / examples**: generic framing; example apps named for the primitive they demo, not a consumer. 4. **Keep**: the repo's own hosting module path `forgejo.coilysiren.me/coilyco-flight-deck/cli-guard` (its identity, not a consumer reference). ## Acceptance - `grep -rE 'coilysiren|\bcoily\b|coilyco-bridge'` over `*.go`/`*.md` returns only the self module path. - `make build` / `make test` / `make vet` green; godoc pin regenerated for any changed exported doc comment. - Large mechanical diff: land in a branch for review. ## Why The fleet now spans multiple consumers (coily, ward, o2r, ...). A framework that narrates itself in one consumer's terms is harder for the others to adopt and reads as proprietary. Generic-by-default is the contract this repo already claims.

coilysiren commented

2026-06-03 10:10:26 +00:00

Author

Owner

Finding: the scrub is two distinct parts

Auditing surfaced that "scrub consumer references" splits into a safe cosmetic part and a functional refactor part. Conflating them is dangerous.

Part A - cosmetic (safe, mechanical)

Provenance issue-refs in comments: coily#130, coilysiren/coily#145, github/forgejo issue URLs -> drop or generic wording.
Prose mentions: "the way coily does X", help text examples -> "the consumer".
Test fixtures using coilysiren/coily as sample owner/repo -> neutral example-org/example-repo.
Docs (AGENTS.md, README, features-detail.md) framing.
No behavior change. This is the bulk of the 384 hits.

Part B - functional consumer-specific DEFAULTS baked into cli-guard (a real leak, NOT a scrub)

cli-guard hardcodes .coily as a functional default in several places:

config/paths.go: GlobalDirName = ".coily", LocalDirName = ".coily".
stscache/stscache.go, scope/scope.go, ghidcache/ghidcache.go: filepath.Join(home, ".coily", "cache").
dispatch/interactive.go: /tmp/coily-dispatch-queue.
verb/verb.go: user-facing error string "coily refuses to forward".

Implications:

Renaming .coily naively breaks coily (it reads ~/.coily).
ward (the other consumer) currently inherits ~/.coily/cache too - a cross-consumer leak that proves the point: the framework should not own a consumer's dir name.
Proper fix is a refactor: make the app-dir / cache-dir / queue-dir configurable (consumer supplies its name via Config), then coily passes ".coily" and ward passes ".ward". This is an API change with coordinated coily/ward updates, not a comment edit.

Proposed slicing

Do Part A under this issue (#49): cosmetic, safe, reviewable diff.
Split Part B into its own refactor issue (configurable app-dir, consumers supply the name) given its blast radius (cli-guard API + coily + ward).

## Finding: the scrub is two distinct parts Auditing surfaced that "scrub consumer references" splits into a safe cosmetic part and a functional refactor part. Conflating them is dangerous. ### Part A - cosmetic (safe, mechanical) - Provenance issue-refs in comments: `coily#130`, `coilysiren/coily#145`, github/forgejo issue URLs -> drop or generic wording. - Prose mentions: "the way coily does X", help text examples -> "the consumer". - Test fixtures using `coilysiren/coily` as sample owner/repo -> neutral `example-org/example-repo`. - Docs (AGENTS.md, README, features-detail.md) framing. - No behavior change. This is the bulk of the 384 hits. ### Part B - functional consumer-specific DEFAULTS baked into cli-guard (a real leak, NOT a scrub) cli-guard hardcodes `.coily` as a functional default in several places: - `config/paths.go`: `GlobalDirName = ".coily"`, `LocalDirName = ".coily"`. - `stscache/stscache.go`, `scope/scope.go`, `ghidcache/ghidcache.go`: `filepath.Join(home, ".coily", "cache")`. - `dispatch/interactive.go`: `/tmp/coily-dispatch-queue`. - `verb/verb.go`: user-facing error string "coily refuses to forward". Implications: - Renaming `.coily` naively **breaks coily** (it reads `~/.coily`). - ward (the other consumer) currently inherits `~/.coily/cache` too - a cross-consumer leak that proves the point: the framework should not own a consumer's dir name. - Proper fix is a **refactor**: make the app-dir / cache-dir / queue-dir configurable (consumer supplies its name via Config), then coily passes ".coily" and ward passes ".ward". This is an API change with coordinated coily/ward updates, not a comment edit. ### Proposed slicing - Do **Part A** under this issue (#49): cosmetic, safe, reviewable diff. - Split **Part B** into its own refactor issue (configurable app-dir, consumers supply the name) given its blast radius (cli-guard API + coily + ward).

coilysiren referenced this issue

2026-06-03 10:12:17 +00:00

make the app-dir (.coily) configurable so the framework owns no consumer's filesystem layout #50

coilysiren referenced this issue

2026-06-03 10:47:29 +00:00

make the app-dir (.coily) configurable so the framework owns no consumer's filesystem layout #50

coilysiren referenced this issue from a commit

2026-06-03 10:51:12 +00:00

chore: scrub consumer-specific references so the library is fully generic (Part A)

coilysiren closed this issue

2026-06-03 10:51:12 +00:00