@kaisers-io/refs 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,228 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.1] - 2026-07-30
+
+### Added
+
+- The npm tarball now ships a package README (the npm page was empty) and this
+  `CHANGELOG.md` — the latter matters because the GitHub repository is private during the
+  current development phase, so the packaged copy is the only changelog users can see.
+  The release pipeline's tarball-content allowlist covers both, and a new guard fails the
+  release if the packaged changelog drifts from the repository one.
+- Registry metadata in `package.json`: `keywords`, `homepage`, and `bugs`.
+
+## [0.5.0] - 2026-07-30
+
+### Added
+
+- Full Windows support: every command, the lock/steal machinery, sync/clone/remove with their
+  containment guards, and the read-only hook guards now behave on Windows exactly as on
+  macOS/Linux (Git for Windows required). CI runs the full test suite plus a PowerShell smoke
+  test — which exercises the npm-generated `.cmd` shims — on `windows-latest`.
+
+### Fixed
+
+- Lock directory names no longer contain `:` (illegal in Windows file names; every locked
+  command failed with `EINVAL` there). Per-ref locks are now named `ref.<key>`; a stale
+  `ref:<key>` directory left by an older version is inert and can be deleted.
+- The lock-steal pipeline treats Windows sharing-violation errors (`EPERM`/`EACCES`/`EBUSY` on
+  the tombstone rename or on re-creating a directory that is still delete-pending) as a lost
+  race and retries, instead of crashing.
+- Workspace package paths are `/`-separated identifiers on every platform (they previously used
+  `\` on Windows, breaking sorting, deduplication, and stored config paths).
+- Child-process cleanup also listens for `SIGBREAK`, so Ctrl-Break on Windows kills spawned
+  git/ssh children like Ctrl-C does.
+
+## [0.4.0] - 2026-07-28
+
+### Changed
+
+- Internal: whole-codebase clarity refactor — comments now explain behavior instead of project
+  history, inline lint exceptions cut from 75 to 20, `type` aliases replace interfaces
+  throughout, dead exports removed, and the workspace-detection logic is split into a pure,
+  directly-tested module. No CLI behavior change.
+
+### Removed
+
+- `refs search` and `refs range` (both added in 0.3.0). A dedicated efficiency benchmark
+  (18-task corpus built around the two commands, taught inline with worked `--json` examples and
+  provably on `PATH`) measured **0 / 324 adoption** — neither Opus 4.8 nor GPT-5.6 invoked either
+  command on a single task, including tasks constructed to favor them — while the condition
+  carrying the teaching cost _more_ (cost-weighted spend +19% over discipline, +41% over naive for
+  Claude). With the dependency source checked out, both commands compete head-to-head with the
+  agent's native `git grep` / `git log` / `git diff` and lose: they are redundant with skills the
+  agent already has on the very source refs provides. refs' core value — real, local source the
+  agent then reads and greps — is unchanged. The agent skill now routes source-search and version
+  questions to `resolve`/`sync`/`tag` plus read-only git on the checkout. The now-dead core helpers
+  (`git/grep`, `git/range`, `git/changelog`) were removed with them.
+
+## [0.3.0] - 2026-07-23
+
+### Added
+
+- `refs range <ref> <old-version> <new-version>` — a bounded version-diff digest for
+  agent-driven "what changed between these versions" questions. Resolves both versions to git
+  tags (same `tag_format` inheritance as `refs tag`) and returns, in one call, the commit count,
+  the newest `--limit` (default 50) non-merge commit subjects, diff stats, changed paths (capped
+  at 200), and a changelog excerpt extracted at the new tag. `--package <name>` scopes the
+  diff/paths/changelog to that package's path while the commit log stays repo-wide. Every bounded
+  list carries an honest flag in `truncated`; the digest is a starting point, and the full history
+  stays available via plain git in the checkout.
+- `refs search <ref> <pattern>` — bounded structured code search over a ref's checkout. Wraps
+  `git grep -z -n -I --extended-regexp` and returns `{path, line, snippet}` matches (trimmed,
+  capped at 200 chars), at most `--limit` (default 50), with `truncated: true` whenever more
+  exist. Vendored/generated paths (`dist`, `build`, `node_modules`, lockfiles, …) are excluded by
+  default and echoed in `excludes_applied`; `--no-default-excludes` turns them off. `--glob` takes
+  plain glob patterns (never raw git pathspec magic — leading `:` or root-escaping `..` are
+  rejected), and `--package` is a hard boundary that intersects with any `--glob` and refuses a
+  package directory resolving outside the checkout. No matches is a success, not an error.
+
+### Changed
+
+- Rewrote the agent skill's investigation playbook (`skills/refs/references/investigate.md`) as an
+  advisory guide built on the "hint, not gate" principle: four hard rules (read real source before
+  citing, treat digests as starting points, honour truncation flags, unmask decoy version tags)
+  plus recommended investigation funnels with explicit escape hatches, tuned by two real-world
+  field tests.
+
+## [0.2.0] - 2026-07-07
+
+### Added
+
+- Onboarding flow for the agent skill (`skills/refs/references/onboarding.md`, triggered by
+  "onboard me" / "set up refs" / "what is refs"): health check via `refs doctor --json`, a
+  consented `refs init` where needed, the three core jobs explained with copyable example
+  prompts, and a first-ref suggestion drawn from the project's own dependency manifests.
+- Install flow in the skill's capability gate: when the `refs` CLI is missing, the agent now
+  checks the Node version, asks the user for consent, installs `@kaisers-io/refs` from npm,
+  verifies with `refs --version`, and runs `refs doctor --json` automatically. A new
+  `compatibility` frontmatter field declares the CLI dependency.
+
+### Changed
+
+- All example content (docs, skill references, README, CLI help text) switched from next.js to
+  zod (`github.com/colinhacks/zod`) — every example validated against a real zod checkout via
+  refs itself.
+- Development now requires pnpm 11 or newer (`engines.pnpm` at the workspace root); the
+  published CLI has no pnpm requirement.
+- The user-facing supported Node range relaxed from `>=24.12 <25` to `>=24.12` (open-ended),
+  verified working on Node 25.9 and 26.4 (build, tests, stub, and source fallback). Development
+  stays pinned to Node 24.12 via `.node-version`; CI and the root `packageManager` field are
+  unchanged.
+- `packages/cli/bin/refs.mjs` is now a committed, zero-dependency stub (not build output): it
+  checks the Node.js version, then loads and runs the tsdown bundle from `dist/refs.mjs`. If the
+  bundle is missing but sources and dependencies are present, it falls back to running the CLI
+  directly from TypeScript source via Node's native type stripping. It fails loudly with an
+  actionable message (exit 1) only if neither the bundle nor the source fallback can load. The
+  tsdown bundle itself moved from `bin/refs.mjs` to `dist/refs.mjs`, and remains gitignored build
+  output produced by `pnpm build`.
+
+## [0.1.3] - 2026-07-05
+
+### Added
+
+- Plugin manifests for the Codex app/CLI (`.codex-plugin/plugin.json`) and Claude Code's
+  plugin marketplace (`.claude-plugin/plugin.json` + `marketplace.json`), plus a
+  `.agents/plugins/marketplace.json` mirror for Codex's own marketplace. A
+  `.agents/skills/refs` symlink to `skills/refs/` gives Codex repo-local
+  auto-discovery of the skill when run inside this checkout.
+
+### Changed
+
+- `packages/cli/bin/refs.mjs` (the built CLI bundle) is no longer committed to the repo — it's
+  build output, regenerated by `pnpm build` and gitignored. CI now proves the build is
+  deterministic (two consecutive builds byte-for-byte identical) instead of diffing a committed
+  copy, and the release pipeline passes the bundle built and guarded by the unprivileged `verify`
+  job to the minimal `publish` job as a workflow artifact, so `publish` still never installs
+  dependencies or runs a build while it holds the npm OIDC token.
+- Updated the bundled `smol-toml` TOML parser/serializer from 1.6.1 to 1.7.0 (faster
+  single-pass string decoding; integers beyond the safe range now serialize as floats;
+  no breaking changes).
+- `refs add <source> --description <text>` no longer reuses `<text>` as a fallback
+  description for detected packages that lack one. `<text>` is now only ever the
+  top-level ref description; if one or more detected packages have no manifest
+  description (including a single-package repo whose lone package has none, and a
+  package whose manifest carries an empty `"description": ""` — the `npm init -y`
+  scaffold), the one-shot fails (exit 3) naming every affected package and pointing at
+  the two-phase `--dry-run`/`--proposal` flow instead. Consequently, an `npm:<pkg>`
+  source without detected workspace packages can effectively never use the one-shot —
+  its single seeded package entry never carries a description — and always needs the
+  two-phase flow.
+
+- Replaced the `execa` dependency with a small hand-rolled `node:child_process`-based
+  process runner. `git`/`ssh` invocations, timeouts, and error handling work as
+  before, with two minor observable differences: a command that fails to spawn at
+  all (e.g. `git` missing from `PATH`) now reports exit code 127 instead of 1, and
+  its OS error message (e.g. `spawn git ENOENT`) now lands on stderr — improving
+  `refs doctor`'s failure detail for a missing `git` binary. The published CLI
+  bundle is smaller as a result (`bin/refs.mjs`: 305,188 → 196,249 bytes raw,
+  89,740 → 55,864 bytes gzipped).
+
+### Fixed
+
+- `refs add --proposal` validation errors now name the offending key(s) for a
+  stray/unrecognized field in the proposal — top-level (e.g.
+  `unrecognized key(s) in proposal: "okay"`) and nested inside a package entry (e.g.
+  `unrecognized key(s) in proposal at packages.<name>: "bogus"`) — instead of a bare,
+  contextless `Invalid input`. Named-field validation errors (missing or wrong-typed
+  fields, including nested package fields like `packages.<name>.description`) are
+  unchanged.
+
+## [0.1.2] - 2026-07-05
+
+### Added
+
+- `refs add` now emits progress lines on stderr while it works (`refs: resolving npm
+package '…'…`, `refs: cloning …`, `refs: detecting workspace packages…`) in both
+  human and `--json` mode, so long clones no longer look like a hang. stdout is
+  unaffected and stays exactly the parseable envelope in `--json` mode.
+
+### Fixed
+
+- `refs add --proposal` now accepts the full `--json` envelope that
+  `refs add … --dry-run --json` prints, so the documented pipe workflow
+  (`refs add npm:x --dry-run --json > f.json` → edit → `refs add --proposal f.json`)
+  works without hand-stripping the `data` wrapper. Bare proposal documents keep
+  working unchanged.
+- A proposal file containing a failed (`ok: false`) or malformed (no usable `data`
+  object) envelope now fails with a clear message instead of a field-by-field
+  validation dump.
+
+## [0.1.1] - 2026-07-05
+
+No user-facing changes. First tag-driven release, validating the OIDC
+trusted-publishing pipeline end to end.
+
+## [0.1.0] - 2026-07-05
+
+### Added
+
+- Initial release of the `refs` CLI: manage local, read-only checkouts of reference
+  repositories ("refs") for agents and humans — `init`, `add` (two-phase
+  proposal/finalize or one-shot `--description`), `list`, `show`, `resolve`, `sync`,
+  `edit`, `remove`, `migrate`, and `doctor`.
+- npm-source resolution (`refs add npm:<package>`), workspace package detection
+  (npm/yarn/pnpm monorepos), tag-format detection, blobless clones with full-clone
+  fallback, and a configurable git transport (`https`/`ssh`).
+- Machine-readable `--json` output with a stable `{ok, data, warnings}` /
+  `{ok, error}` envelope on every command, plus stable exit codes.
+- Containment-guarded destructive operations, credential redaction in every
+  URL-carrying message, and read-only enforcement of managed checkouts via
+  installed git hooks.
+- Agent skill (`skills/refs/`) documenting the investigate/add/maintain workflows.
+
+[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/kaisers-io/refs/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/kaisers-io/refs/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/kaisers-io/refs/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/kaisers-io/refs/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/kaisers-io/refs/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/kaisers-io/refs/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/kaisers-io/refs/releases/tag/v0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @kaisers-io/refs
+
+**Real source code for coding agents.**
+
+`refs` manages arbitrary git repositories (GitHub, GitLab, self-hosted) as local, managed
+read-only source-code references, so that coding agents answer questions about
+dependencies and reference projects against **real source code** — never against a
+minified `node_modules` bundle, never against stale training knowledge.
+
+When your project depends on `zod`, you say "add zod as a ref"; `refs` resolves the npm
+package to its git repository, clones it, detects its release-tag convention and monorepo
+packages, and from then on any agent can answer "what changed between v4.0.0 and v4.1.0"
+or "how does zod implement codecs" by reading the actual checkout.
+
+npm is only a convenience resolver (`npm:zod`). Arbitrary git URLs work directly.
+
+**Read-only is a workflow promise, not a security boundary.** Every checkout under
+`sources/` is a managed reference, not a working copy: agents are instructed never to
+edit, commit, or push inside one. `refs` installs git hooks that reject commits/pushes in
+a checkout as a backstop, and `refs sync` self-heals a dirty checkout if something slips
+through anyway — but this is discipline enforced by convention and tooling, not a sandbox.
+
+## Install
+
+Requirements: Node.js `>=24.12` and git. macOS, Linux, and Windows are fully supported —
+every command, locking, sync, and the read-only guards behave the same on all three (on
+Windows, use [Git for Windows](https://gitforwindows.org/)).
+
+```bash
+npm i -g @kaisers-io/refs
+```
+
+Then verify the setup:
+
+```bash
+refs --version
+refs doctor
+```
+
+## Quickstart
+
+```bash
+# 1. Seed the refs home directory, config, and git hooks guard.
+refs init
+
+# 2. Propose adding a ref — resolves npm:zod to its git repo, clones it, and writes
+#    a reviewable proposal. Nothing is added to config yet.
+refs add npm:zod --dry-run
+
+# 3. Review the proposal JSON, then finalize it, or use --description for a
+#    one-shot add:
+refs add npm:zod --description "TypeScript-first schema validation" --json
+```
+
+Every command accepts `--json` for a stable, machine-readable envelope and `--verbose`
+for stack traces on error. Run `refs --help` or `refs <command> --help` — the CLI's own
+help is the authoritative, always-current reference.
+
+## Commands
+
+| Command        | What it does                                                                            |
+| -------------- | --------------------------------------------------------------------------------------- |
+| `refs init`    | Seed or migrate the refs home directory, its config, and the git hooks guard.           |
+| `refs add`     | Add a git reference in two phases: propose (`--dry-run`), then finalize (`--proposal`). |
+| `refs list`    | List configured refs with their staleness/missing checkout status.                      |
+| `refs show`    | Show a configured ref: full entry, state, local path, and sample tags.                  |
+| `refs sync`    | Fetch (or re-clone, if the checkout is missing) configured refs — all by default.       |
+| `refs resolve` | Resolve a git url, npm package name, import path, or ref-key suffix to its ref/package. |
+| `refs tag`     | Resolve a version to its git tag, via the ref's (or a package's) `tag_format`.          |
+| `refs edit`    | Edit one field of a global setting, a ref, or a package.                                |
+| `refs remove`  | Remove a configured ref: its config/state entry AND its checkout directory.             |
+| `refs doctor`  | Run environment/integrity checks (git, node, config, hooks, checkouts, ssh).            |
+| `refs migrate` | Migrate the refs config to the current schema, seeding it if absent.                    |
+
+## Agent skill
+
+The CLI pairs with one thin, cross-agent skill (Claude Code and Codex) that routes agent
+questions ("how does zod implement codecs") to the right checkout via `refs resolve
+--json` and keeps things fresh with `refs sync`/`refs doctor`. `refs init` prints the
+exact install command for your setup. The skill is distributed from the GitHub
+repository, which is private during the current development phase — it opens up when
+`refs` goes public.
+
+## Changelog
+
+`CHANGELOG.md` ships inside this package (npm's "Code" tab shows it) — the GitHub
+repository is private during the current development phase.
+
+## License
+
+MIT