Person/codekiln/GitHub/sourcer/Project/Log/26/05/17 Sun

• 2026-05-17 Sun
  • Got frustrated with the AI-generated specs in Person/codekiln/GitHub/sourcer/Project/v0 AI Spec and sub-namespaces. Every time I try to use AI to design a CLI like this, it seems like it ends up generating so much AI/Slop.
    • It proposes CLI commands and configuration options that add little utility, doesn't follow a coherent philosophy, but adds a lot of maintenance burden.

      • For example, it suggested adding srcr status which is implied by or derivative of git/status

        • • srcr status

            • Compare desired vs realized state for each declared source (and optionally scan disk for undeclared trees).
            • Human output: table of identity, ref wanted, ref on disk, dirty/clean, allowed, path.
            • JSON: array of per-source status objects (schema aligned with use output fields; see Phase 2).
            • Use when: "why is my agent not seeing library X?" before diving into git manually.
        • I don't see any reason for this.
      • As another example, it suggested adding configuration options in toml for specifying the ref that should be downloaded

        • • Object form

            • toml

              [sources]
              "github.com/example/project" = "main"
              "github.com/example/private-tool" = { ref = "main", clone = "ssh" }
              "internal.example.com/platform/tool" = {
                ref = "main",
                remote = "ssh://git@internal.example.com/platform/tool.git"
              }

            • MVP object keys (intentionally small):
              • ref — branch, tag, or commit-ish name (required when using object form).
              • clone — transport preference: "https" | "ssh" (provider may default to https for public hosts).
              • remote — full clone URL when identity alone is insufficient (self-hosted, non-standard paths).
              • path — override local directory relative to root; use only when layout cannot follow the default convention.
            • Provider defaults should derive:
              • HTTPS clone URL from identity when remote is omitted.
              • Default path root/<identity-as-path> e.g. ~/sources/github.com/example/project.
        • all of these options provide a feature: ability to specify parts of a repo, but each new option opens up a space for bugs. It's very difficult to get AI to come up with designs that are minimal, verifiable, and move away from surface area and towards simplicity.
      • I tried having it lead me through some design thinking, starting with a stakeholder empathy map:

        • • Stakeholder empathy map

            • Solo developer

              • Says: "I know this library is on GitHub somewhere — where did I clone it last time?" / "Let me git clone into ~/projects again."
              • Thinks: Onboarding should be one obvious path; I should not maintain a mental map of ten clone locations; mise-style declarative setup should work for repos too.
              • Feels: Annoyed by duplicate clones and wasted disk; relieved when rg works across an org cache; wary of agents doing their own thing in /tmp.
              • Does: Ad hoc git clone; bookmarks paths in shell aliases; sometimes adds git submodules and regrets it; runs agents against whatever paths the tool invents.

            • Platform / security team

              • Says: "Agents cannot have repo:all." / "We need an auditable allowlist, not 'whatever the model asks for'."
              • Thinks: Prompt injection on hosting sites is real; whitelisting github.com is insufficient; local corpus must be bounded and policy-driven.
              • Feels: Pressure to enable AI productivity without reopening the whole internet; skeptical of tools that fail open.
              • Does: Network egress rules; PAT scopes; reviews agent tool configs; pushes standardized dev images and config fragments ([sources], Phase 2 [allow]).

            • AI agent operator

              • Says: "Read the implementation before you refactor." / "Use structured output so the planner does not guess paths."
              • Thinks: Primary source beats docs; paths must be deterministic across sessions; allowed: false must hard-stop automation.
              • Feels: Frustrated when agents clone to /tmp and discard context; anxious about injection via issue comments when browsing live repos.
              • Does (MVP): srcr install + srcr where / status --json; pre-bakes corpora in sandboxes; prompts reference canonical identity, not host paths.
              • Does (Phase 2): wraps srcr use … --json for optional repos not in install set.

            • OSS contributor

              • Says: "I forked upstream — which path is 'the' one for search?" / "I do not want a corporate trust file for a weekend hack."
              • Thinks: Defaults should be lightweight; public GitHub identities should work without a security team; shared cache still helps across my own projects.
              • Feels: Wary of heavy ceremony; willing to adopt convention if install is one command after editing a small TOML.
              • Does: Clones into ~/src or ~/go/src-style trees; uses upstream + fork remotes manually; contributes without org-wide policy.

            • DevContainer maintainer

              • Says: "Our devcontainer only has the service repo — engineers still need contracts and shared libs on disk."
              • Thinks: postCreateCommand clone scripts rot; Docker layer caching matters; trust at build time must match runtime agent profile.
              • Feels: Stuck between single-repo templates and fragile shell scripts; wants mise-native ergonomics without submodule weight.
              • Does: Hand-rolls git clone in Dockerfile or postCreateCommand; bind-mounts host caches sometimes; pairs with mise for tools.

            • CI author

              • Says: "The job needs to grep two other repos before tests run." / "Fail the pipeline if required sources are missing or wrong ref."
              • Thinks: Same srcr.toml as local dev; JSON status for gates; no interactive allow break-glass in CI.
              • Feels: Impatient with non-deterministic paths; needs exit codes that distinguish not-allowed vs git vs config errors.
              • Does: Runs install in setup job; uses srcr where in scripts; caches root between runs when policy allows.
        • In theory this makes sense, but it just feels sloppy. One of my key stakeholders is the AI agent itself, and that's not even listed. There's AI agent operator, but not AI agent. Also, it gets rather fixated with things that are not central to the design. Why is "OSS contributor" saying "I do not want a corporate trust file for a weekend hack?" of course OSS contributors wouldn't want that, but in what world would that stakeholder say that? it implies something: that we need a corporate trust file. That opens up a whole world where AI/Coding/Concept/Heresy can enter the system.
  • What I want in v1 is likely just the simplest thing possible
    • principles
      • written in idiomatic rust
      • well-tested
      • secure
        • as few dependencies as possible
      • simple and understandable. anti-complicated. does one thing well.
        • anyone should feel like they can read the source and grok it
        • prefer fewer features rather than feature rich and bloated
    • use cases
      • 0.1.x - getting started
        • sourcer --version prints version
        • sourcer --help prints help saying it does nothing as of yet
        • README.md exists
        • ability to generate sourcer binary in github CI and publish to release using semvar and conventional commits
        • ability to install sourcer binary from github release
          • instructions on how to install as a mise tool
        • each PR should generate and publish a new version
        • PR CI checks
          • rust formatting
          • unit test
          • integration test
            • target environment for integration test: devcontainer
      • 0.2.x - the most basic feature that can make it useful
        • sourcer get <repo-ref> - get the repo
          • if it doesn't exist on disk
            • clone the repo into the folder specified by the convention
              • exit code 0
            • if it isn't clone-able
              • display error
              • nonzero exit code
          • if it already exists locally,
            • print the location of the repo locally
            • nonzero exit code
      • 0.3.x - the next most useful thing that can make it useful
        • sourcer list - list all the repos in <sourcer-root>
          • for piping into fzf
          • is there a way this can be done without adding a feature to sourcer, for example, just with ls?
      • 0.4.x
        • sourcer migrate [<repo-path>]
          • if <repo-path> or CWD is a valid repo that is outside place it should be according to the sourcer system, move it to the place it should be according to sourcer
      • 0.5.x
        • sourcer config
          • display the configuration file and its location
        • sourcer config SOURCES_ROOT [<file-path>]
          • if [<file-path>]
            • if its valid
              • write the config file to set the file path for the SOURCES_ROOT
            • if invalid path
              • nonzero exit code
          • if config exists and SOURCES_ROOT is in it
            • display the value of SOURCES_ROOT
          • display default value of SOURCES_ROOT
      • 0.6.x
        • ability to specify in a config file
          • what repo refs or repo ref patterns are approved for clone when needed
  • Later I could consider
    • sourcer migrate
    • sourcer search - search for names of repos
      • sourcer search [gh|github|gl|gitlab|cb|codeberg|sh|sourcehut|...] <owner>/<repo-prefix>
    • sourcer goto <repo-ref> - cd to the local repo
      • unnecessary! we can just cd there
  • 14:19 discovered ghq which does basically what I'm looking for.
    • comparison
      • written in go instead of rust
      • doesn't use a config file to declare repositories that are safe to clone or ones to pre-clone in advance
      • does use git/.gitconfig to configure it, which seems smart