@osdlc/repo-cleaner 0.0.0-stage → 0.5.2

package/README.md

@@ -1,3 +1,302 @@
-# Temporary Holding Version
+# @osdlc/repo-cleaner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What has been merged into the default branch, and what can go away.
+
+Point it at a repository and it inventories the local branches, worktrees and
+remote branches, classifying each as `safe-to-delete`, `safe-to-keep` or
+`needs-investigation` — with the evidence behind the verdict and the literal
+command that would act on it.
+
+The sweep never deletes anything. It emits commands, and can write the
+deletable rows as a plan. `repo-cleaner apply` deletes the plan rows you
+select, after checking each one again.
+
+```console
+$ repo-cleaner
+/Users/me/work/api  (acme/api, default main, origin)
+  local_branch   fix/login-redirect   delete  PR #412 merged
+                 git update-ref -d refs/heads/fix/login-redirect 3f9c2e1d8b7a6c5d4e3f2a1b0c9d8e7f6a5b4c3d
+  local_branch   spike/cache          review  mixed or absent signals
+  worktree       wt/412               delete  clean; PR #412 merged
+                 git -C /Users/me/work/api worktree remove wt/412
+  remote_branch  origin/fix/login-…   delete  PR #412 merged (auto-delete didn't fire)
+                 git push --force-with-lease=refs/heads/fix/login-redirect:3f9c2e1d8b7a6c5d4e3f2a1b0c9d8e7f6a5b4c3d origin :refs/heads/fix/login-redirect
+
+1 to delete, 1 to review, across 1 repository.
+```
+
+## Install
+
+```sh
+npm install @osdlc/repo-cleaner
+```
+
+ESM only. Compiled JavaScript with type declarations, for Node 22 or newer.
+
+## How it decides
+
+Two signals settle most items, and either alone is enough:
+
+| Signal | Source |
+| --- | --- |
+| A `MERGED` pull request from this repository, into the default branch, whose head commit is the branch tip | `gh pr list`, one listing per repository |
+| The branch tip is reachable from the default branch | `git merge-base --is-ancestor` |
+
+Ancestry is measured against `<remote>/<default>`, so work merged only into an
+unpushed local default branch does not count. Without a remote, the local
+default branch is used.
+
+A merged PR that fails the head or base check is kept in `facts.pr` with
+`evidence` set to `head-moved` or `other-base`. Fork PRs are ignored.
+
+Everything else is held back. A branch that is neither merged nor an ancestor
+is `needs-investigation` with the reasons spelled out, not a guess. A worktree
+holding uncommitted or unpushed work is never proposed for removal whatever
+else is true of it — losing an hour of someone's work costs more than any
+amount of clutter.
+
+Some worktrees are held back whatever their branch says. Each lands in
+`facts.blockers`, and the row carries no command and has `deletable: false`:
+
+| Blocker | Why |
+| --- | --- |
+| `locked-worktree` | Someone ran `git worktree lock` and the lock's owner is alive or unknown; the reason is in `facts.lock_reason`. A lock whose owner is dead is not a blocker (see below). |
+| `live-process` | A process other than an idle shell has its working directory in the worktree (`facts.live_processes`), lock or not. |
+| `process-probe-failed` | The process table could not be read (no `lsof`, a timeout, an `lsof` that failed outright), so nobody can say the directory is idle. `facts.process_probe_error` has the message. |
+| `hidden-index-flags` | Files marked skip-worktree or assume-unchanged hide edits from `status`. |
+| `nested-repository` | An untracked or ignored directory holds a repository with its own history. |
+| `branch-in-other-worktree` | Another worktree has the same branch checked out (`facts.other_worktrees`). |
+
+### Locks and running processes
+
+A crashed coding agent leaves its worktree locked. The sweep reads one generic
+token from the lock reason, `pid <N>`, optionally followed by `start <time>`,
+and asks whether that process is still running. It reads nothing else of the
+reason, so a free-form reason such as `keep, build running` always blocks.
+
+- The owner is dead: the lock is not a blocker. `facts.stale_lock` is `true`,
+  `facts.lock_owner` holds the pid and start time, and the row's commands begin
+  with `git worktree unlock`. `apply` unlocks, removes and verifies it, and the
+  receipt records the `unlock-worktree` step.
+- The owner is alive, or cannot be ruled out: `locked-worktree`.
+- A lock writes `pid <N>` and, to guard against pid reuse, `start <time>`. The
+  time must be precise to the second: a full ISO-8601 timestamp with a time of
+  day and a zone (`2026-10-25T18:22:19Z`; one with no zone is not accepted), epoch seconds (9-10 digits), epoch milliseconds
+  (12-13 digits), or the `ps -o lstart` form (`Sat Oct 25 18:22:19 2026`). With
+  one of those, a live pid whose own start time differs by more than two
+  seconds is a reused pid and counts as dead. Anything else, a date alone, a
+  short number or a partial date, cannot rule the owner out and the lock stays
+  a blocker.
+- Only `ps` exiting 1 with no output and no error text means "no such pid".
+  Any other `ps` failure counts as alive.
+- The `pid` token is trusted as a local pid. A pid from another container or
+  host that shares the filesystem is looked up here, will not be found, and
+  reads as dead; do not sweep a repository whose locks were written elsewhere.
+- Before the unlock and again before the remove, `apply` asks again, and reads
+  the process table afresh. If the owner is alive by then, or a process other
+  than an idle shell works in the directory, or the table cannot be read, the
+  step fails and the run stops. A row dropped at the re-sweep touches nothing;
+  a step that fails at the unlock leaves the lock in place. `stale_lock` is part
+  of a worktree row's fingerprint, so a lock taken after the plan was written
+  drops the row too.
+- If the remove fails after the unlock succeeded, the lock stays cleared:
+  `@osdlc/typed-git` has no `worktree lock` verb to put it back. The failed
+  step's receipt error says so.
+- Separately, any process whose working directory is inside the worktree blocks
+  it as `live-process`, lock or not. A shell (`sh`, `bash`, `zsh`, `fish`) is
+  idle only when it has no child processes; it is then listed in
+  `facts.idle_shells` and does not block. A shell with a child, or whose
+  children are unknown, counts as a live process.
+
+Both questions go to a `ProcessProbe` (`alive(pid, startedAt?)` and
+`holders(path, { fresh? })`), passed as `probe` in the options of `sweepRepo`,
+`sweepRepos` and `applyPlan`. The default, `defaultProcessProbe()`, runs
+`ps -o lstart=`, `ps -A -o pid=,ppid=` and `lsof -d cwd` through
+`@osdlc/command-seam`, and needs `ps` and `lsof` on `PATH`. It reads the
+process table once per probe and reuses it for every worktree: `sweepRepo`
+makes one probe per call, and `applyPlan` uses one probe for its re-sweep and
+reads the table afresh for each pre-unlock and pre-remove check. Where the
+table cannot be read the worktree is held back as `process-probe-failed`. A
+host or test supplies its own probe.
+Nothing is ever killed.
+
+Without `gh`, or without authentication, classification proceeds on git
+evidence alone and the report says so.
+
+Every branch delete names the full sha the sweep judged. `update-ref -d` and
+the pinned `--force-with-lease` push both refuse when the branch has moved
+since, so a commit pushed while you read the plan survives it.
+`localDeleteCommand` and `remoteDeleteCommand` build them for hosts that add
+their own rows.
+
+Every row names, in `requires`, the risks its delete carries, so a person
+approves them by name:
+
+| Authorization | When a row needs it |
+| --- | --- |
+| `abandon-unmerged` | Commits not on the default branch and not captured by an exact-head merged PR; a worktree's unpushed commits. `facts.unique_commits` counts them. |
+| `discard-changes` | A worktree has modified, staged or untracked files. |
+| `confirm-open-pr` | The branch has an open PR. |
+
+A row kept for structure (default branch, current HEAD, a branch held by a
+worktree, the primary or caller's worktree) has `deletable: false`.
+
+## Scope is opt-in
+
+```bash
+repo-cleaner                        # the repository you are standing in
+repo-cleaner ~/work/api ~/work/web  # named repositories
+repo-cleaner ~/Developer            # every checkout under it
+repo-cleaner --all                  # every repository in the config file
+```
+
+A bare invocation never fans out. What an argument names is read off the disk
+rather than from how it is written: a path that is itself a checkout names
+that repository, and a path that is not is searched for the checkouts under
+it, descending through directories that are not checkouts — an owner
+directory, a folder per client — and stopping at the ones that are.
+
+A linked worktree collapses into the repository it belongs to, so a directory
+holding a checkout and three of its worktrees sweeps one repository, not four.
+Those worktrees still appear — as worktree rows in that repository's own
+inventory.
+
+The report ends with what the search cost — `searched 1 entry: 214
+directories read, 12 checkouts found.` — because those numbers are how an
+entry pointing at the wrong directory gets caught. A search that passes
+10,000 directories says so on stderr while it is still running, and the walk
+stops descending three levels below the entry.
+
+An entry that resolves to nothing is reported rather than dropped. A worklist
+that silently sweeps four of the five repositories it was given is worse than
+one that says which it could not find.
+
+## Options
+
+| Flag | Effect |
+| --- | --- |
+| `--all` | Sweep the repositories named in the config file |
+| `--config <path>` | Config file to read |
+| `--scope <list>` | `local-branches`, `worktrees`, `remote-branches` |
+| `--remote <name>` | Remote to measure against (default `origin`) |
+| `--no-gh` | Classify on git evidence alone |
+| `--no-fetch` | Skip the fetch; the header then says `not fetched` |
+| `--keep` | Include `safe-to-keep` rows in the report |
+| `--commands` | Print the proposed commands of rows that need no authorization, and nothing else |
+| `--output json` | The full inventory, facts included |
+| `--branch <name\|HEAD>` | Sweep one branch of this repository: its worktree, local and remote branch. Refuses the default branch |
+| `--write-plan` | Write the deletable rows as a plan for `apply` |
+| `--plan-out <path>` | Write the plan here; implies `--write-plan` |
+
+A checkout directory named `apply` is swept as `./apply`.
+
+## Plan and apply
+
+```bash
+repo-cleaner --branch HEAD --plan-out plan.json
+repo-cleaner apply --plan plan.json --row worktree:/path/to/wt --row local_branch:feat/x
+```
+
+A plan holds each deletable row with a fingerprint of the facts behind its
+verdict. `apply` sweeps again and drops a selected row that is gone, no longer
+deletable, whose facts moved, or whose `requires` was not granted with
+`--authorize <name>` (every row) or `--authorize <name>=<category>:<id>` (one
+row). It then removes worktrees, deletes local branches, deletes remote
+branches and prunes, in that order. Branch deletes are compare-and-swap, every
+step is verified, and the first failure stops the run.
+
+A receipt records every step and is rewritten after each one. Plans and receipts go under
+`repo-cleaner/plans/` and `repo-cleaner/receipts/` in
+[`@osdlc/tiered-dirs`](https://www.npmjs.com/package/@osdlc/tiered-dirs)' standalone durable home
+(`repo-cleaner` directory, `REPO_CLEANER_*` override variables), unless `--plan-out` or `--receipt-dir` says
+otherwise. `--dry-run` checks again and prints the steps without writing anything.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Swept; or every selected row was applied or dropped with a reason |
+| `1` | Failed against the state it found: a `{name}` token nothing defines, an unreadable plan, a row not in the plan |
+| `2` | Cannot run as typed: an unknown flag, a malformed `--row`, `--branch` with `--all` or a path |
+| `10` | Nothing to sweep: no entry named a repository |
+| `11` | `apply` stopped at a failed step; the receipt says which |
+
+## Configuration
+
+Only the CLI reads a config file. The library takes repositories as an
+argument, so a host that already knows where its repositories are passes them
+in.
+
+```yaml
+paths:
+  dev: ~/Developer
+repos:
+  - '{dev}'
+  - ~/work/api
+```
+
+`paths:` names a directory once; any `repos:` entry then refers to it as
+`{name}`. A token nothing defines is an error, not an empty path.
+
+The file is [`@osdlc/config-layers`](https://www.npmjs.com/package/@osdlc/config-layers)'s machine config — `config.yaml` in the host
+OS's config home, resolved through
+[`@osdlc/tiered-dirs`](https://www.npmjs.com/package/@osdlc/tiered-dirs)' standalone tier (`repo-cleaner`
+directory, `REPO_CLEANER_*` override variables):
+
+| OS | Path |
+| --- | --- |
+| macOS | `~/Library/Application Support/repo-cleaner/config.yaml` |
+| Linux and other | `$XDG_CONFIG_HOME/repo-cleaner/config.yaml`, else `~/.config/repo-cleaner/config.yaml` |
+| Windows | `%APPDATA%\repo-cleaner\config.yaml` |
+
+`REPO_CLEANER_MACHINE_CONFIG`, or `--config <path>`, relocates it. A missing,
+unreadable or malformed file degrades to no repositories rather than failing
+the run.
+
+## As a library
+
+```ts
+import { sweepRepo, sweepRepos } from '@osdlc/repo-cleaner'
+
+const sweep = sweepRepo('/Users/me/work/api', { noGh: true })
+for (const item of sweep.items) {
+  console.log(item.classification, item.id, item.reason)
+}
+
+const result = sweepRepos(['~/Developer'], { cwd: process.cwd() })
+```
+
+`sweepRepo` never throws for a repository it cannot read: the failure comes
+back as `error`, because a fan-out must not end on its first bad entry.
+
+`fetch: true` runs `git fetch --prune --quiet --no-write-fetch-head <remote>`
+before classifying, so ancestry is read against fresh remote-tracking refs.
+That fetch is the only write. A repository whose fetch fails comes back with `error` starting
+`fetch failed:` and no items. `repo.fetched` says which case applied. The
+library default is off; the CLI fetches unless given `--no-fetch`.
+
+### Adding knowledge the library does not have
+
+Every row carries the facts behind its verdict, and `investigationParts` is a
+list of sentences rather than a finished string. That is deliberate: a host
+that knows something git does not — an issue tracker, a task corpus — re-ranks
+the returned rows and appends its own sentence, instead of reaching into
+classification. `applyPlan` takes the same re-ranking as its `annotate` hook,
+so the rows it checks again are the rows the host planned from.
+
+This works because of how the ladder is ordered. Every verdict the sweep
+reaches on its own evidence outranks anything a host could contribute, so a
+host never has to veto one. It only sharpens the rows left at `safe-to-keep`
+or `needs-investigation`.
+
+An issue tracker's linkage, applied this way, is a host's own layer over the
+sweep and `applyPlan`.
+
+## Runtime dependencies
+
+`git` on `PATH`, and `gh` when PR state should count. Authentication is `gh`'s
+own — this package reads no token.
+
+## Licence
+
+`MIT OR Apache-2.0`, at your option. See [LICENSE-MIT](./LICENSE-MIT) and [LICENSE-APACHE](./LICENSE-APACHE).

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report vulnerabilities privately. Do not open a public issue.
+
+Use GitHub private vulnerability reporting on the repository: open the
+[Security tab](https://github.com/osdlc/osdlc/security) and choose
+"Report a vulnerability".
+
+Include the version, a short description, and steps to reproduce.
+
+## Supported versions
+
+Only the latest release gets security fixes. While the version is 0.x, that
+is the latest minor release.
+
+## What to expect
+
+This is a small project. We aim to reply within a week, tell you whether we
+accept the report, and credit you in the release notes if you want that.

package/bin/repo-cleaner.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// The published entry point: `npx @osdlc/repo-cleaner …` and a plain
+// `node ./bin/repo-cleaner.js …` both land here. Requires the built dist/cli.js
+// (`pnpm run build`).
+import { runMain } from '@osdlc/cli-tool'
+import { main } from '../dist/cli.js'
+
+await runMain(main, { name: 'repo-cleaner' })

package/dist/apply.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Apply an approved cleanup plan.
+ *
+ * Re-sweeps each repository and drops selected rows that are gone, no longer
+ * deletable, changed, or lack a grant. Deletes the rest in a fixed order and
+ * stops at the first failure:
+ *
+ * 1. worktrees, each unlocked first when its lock's owner is dead, and each
+ *    checked again for live processes just before it is unlocked or removed;
+ * 2. local branches;
+ * 3. remote branches;
+ * 4. one prune per repository.
+ *
+ * Branch deletes are compare-and-swap on the planned sha. Every step is
+ * verified, and the receipt is rewritten after each.
+ */
+import type { CommandRunner } from '@osdlc/command-seam';
+import type { HostHooks } from './hooks.ts';
+import { type ProcessProbe } from './processes.ts';
+import { type Plan } from './plan.ts';
+import type { Receipt, RowRef } from './receipt.ts';
+import { type Authorization } from './types.ts';
+/** An authorization the caller gave, for one row or (`row: null`) for all. */
+export interface Grant {
+    name: Authorization;
+    row: RowRef | null;
+}
+export interface ApplyOptions extends HostHooks {
+    /** Injected runners. Defaults spawn the real `git` and `gh`. */
+    git?: CommandRunner | undefined;
+    gh?: CommandRunner | undefined;
+    /**
+     * Answers lock-owner and working-directory questions, for the re-sweep and
+     * for the checks just before an unlock and a remove. Defaults to `ps` and
+     * `lsof`.
+     */
+    probe?: ProcessProbe | undefined;
+    /** The caller's directory; the sweep never offers the worktree holding it. */
+    callerCwd: string;
+    dryRun: boolean;
+    /** Where the receipt goes. Unused under `dryRun`. */
+    receiptPath: string;
+    /** Shown in the receipt. */
+    planPath: string;
+    /** Limit the run to the plan repository rooted here. */
+    repoRoot?: string | undefined;
+    now?: () => Date;
+}
+/** A selection or grant the plan cannot satisfy. Nothing has been touched. */
+export declare class ApplyArgumentError extends Error {
+}
+/** `<category>:<id>`, split at the first colon. */
+export declare function parseRowRef(text: string): RowRef;
+/** `<name>` for every row, or `<name>=<category>:<id>` for one. */
+export declare function parseGrant(text: string): Grant;
+/**
+ * Apply the `requested` rows of `plan` under `grants`. A row named twice runs once.
+ *
+ * @throws ApplyArgumentError before touching anything, when a row or grant does
+ *   not fit the plan.
+ */
+export declare function applyPlan(plan: Plan, requested: readonly RowRef[], grants: readonly Grant[], opts: ApplyOptions): Receipt;