{"_id":"@alexissliwak/repo-lib","name":"@alexissliwak/repo-lib","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alexissliwak/repo-lib","version":"0.1.0","description":"Keep private, untracked project files locally while source code lives in remote Git repositories.","type":"module","bin":{"repo-lib":"dist/cli.js"},"engines":{"node":">=22.12","pnpm":">=11.15.1"},"publishConfig":{"access":"public"},"keywords":["cli","git","ink","secrets","worktree"],"license":"MIT","dependencies":{"@inkjs/ui":"^2.0.0","ink":"^7.1.1","react":"^19.2.0"},"devDependencies":{"@types/node":"^24.10.0","@types/react":"^19.2.0","@vitest/coverage-v8":"^4.1.10","ink-testing-library":"^4.0.0","typescript":"^7.0.2","vitest":"^4.1.10"},"repository":{"type":"git","url":"https://github.com/AlexisSliwak/repo-lib.git"},"homepage":"https://github.com/AlexisSliwak/repo-lib#readme","bugs":{"url":"https://github.com/AlexisSliwak/repo-lib/issues"},"scripts":{"clean":"node scripts/clean.mjs","build":"pnpm run clean && tsc -p tsconfig.build.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"vitest run","coverage":"vitest run --coverage","pack:verify":"node scripts/verify-pack.mjs"},"_nodeVersion":"24.14.0","_id":"@alexissliwak/repo-lib@0.1.0","dist":{"integrity":"sha512-I0l5ZiA11LdNgVYaTg/THuVmUffq1JGYsOV2EJxgZBvKhixIMYB+3vW/76yjX7QUMVUm76+Yf0roNr1jQEQZNw==","shasum":"8d157506d2c1b48aebec329cfebc3c1873547746","tarball":"https://registry.npmjs.org/@alexissliwak/repo-lib/-/repo-lib-0.1.0.tgz","fileCount":43,"unpackedSize":179102,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCtkMDSE5WNAAHCjEKw9njXrGAoELnewV2GT3Ukwro1hAIhAIvBaFUzxM1i5Y1+lrXk8BUjIi6FJ41jRDqbTnpGElxT"}]},"_npmUser":{"name":"alexissliwak","email":"sliwakalexis@gmail.com"},"directories":{},"maintainers":[{"name":"alexissliwak","email":"sliwakalexis@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/repo-lib_0.1.0_1785326252729_0.9167975177955385"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-29T11:57:32.581Z","0.1.0":"2026-07-29T11:57:32.873Z","modified":"2026-07-29T11:57:33.214Z"},"maintainers":[{"name":"alexissliwak","email":"sliwakalexis@gmail.com"}],"description":"Keep private, untracked project files locally while source code lives in remote Git repositories.","homepage":"https://github.com/AlexisSliwak/repo-lib#readme","keywords":["cli","git","ink","secrets","worktree"],"repository":{"type":"git","url":"https://github.com/AlexisSliwak/repo-lib.git"},"bugs":{"url":"https://github.com/AlexisSliwak/repo-lib/issues"},"license":"MIT","readme":"# repo-lib\n\n`repo-lib` is a small local companion for projects whose source code lives in\nremote Git repositories. It keeps only untracked, machine-local project files\nsuch as `.env` files in a separate **library**, then restores those files into\nthe corresponding project in a **worktree**.\n\n> [!WARNING]\n> The library is plain, unencrypted storage and may contain passwords, API keys,\n> certificates, and other secrets. Keep it private, protect it with appropriate\n> filesystem permissions and backups, and never publish or commit it.\n\n`repo-lib` is an interactive terminal application built with React and Ink. It\nrequires Node.js **22.12 or newer**.\n\n## Concepts\n\n- The **worktree root** contains normal Git projects.\n- The **library root** mirrors project paths beneath the worktree root.\n- Each registered remote-backed project has a reserved `remote-repo.txt` file\n  containing its selected Git fetch URL.\n- Tracked Git files are never stored in the library. This includes files staged\n  for addition and files deleted from disk but still present in the index.\n- Nested Git repositories, submodules, and linked worktrees are separate\n  projects. Operations on a parent project do not enter them.\n- The current project is determined from the current directory with Git's\n  project root. It must be registered beneath the configured worktree root.\n\nOne active library/worktree pair is stored in the operating system's user\nconfiguration directory.\n\n## Quick start\n\nRun the published CLI without installing it globally:\n\n```sh\nnpx @alexissliwak/repo-lib init\n```\n\nYou can also install it globally with pnpm:\n\n```sh\npnpm add --global @alexissliwak/repo-lib\nrepo-lib --help\n```\n\nDuring `init`, choose one of two modes:\n\n1. **Create an empty library** records the library and worktree roots without\n   importing project payload.\n2. **Build from an existing worktree** discovers Git projects under the chosen\n   worktree. A project with one remote is associated automatically; if it has\n   several, you select one. Only `remote-repo.txt` markers are created—tracked\n   and untracked worktree files are not copied.\n\nIf a discovered repository has no remote, `init` explains that its tracked\nsource will not be backed up and asks whether to register it as local-only. You\ncan add a Git remote later and run `npx @alexissliwak/repo-lib push`.\n\nThe library destination must be empty, and the library and worktree roots must\nnot overlap.\n\n## Commands\n\nRun project commands from anywhere inside the intended Git project.\n\n### `repo-lib init`\n\nInteractively creates the active configuration and optionally discovers\nprojects in an existing worktree.\n\n```sh\nnpx @alexissliwak/repo-lib init\n```\n\nInitialization shows the plaintext-storage warning before configuration is\nsaved. It does not copy untracked files from an existing worktree.\n\n### `repo-lib add <path...>`\n\nExplicitly adds files or directories from the current project to its library:\n\n```sh\nnpx @alexissliwak/repo-lib add .env config/local.json private-certs/\n```\n\nDirectories are traversed recursively. Only untracked regular files are copied.\nExplicitly named ignored files are eligible, which makes `add` the appropriate\ncommand for `.env` and similar files. Tracked files, `.git`,\n`remote-repo.txt`, nested projects, symlinks, and junctions are skipped.\n\nAll paths must remain inside the current Git project.\n\n### `repo-lib push [--all]`\n\nUpdates the library from the current worktree:\n\n```sh\n# Refresh only payload already represented in the library\nnpx @alexissliwak/repo-lib push\n\n# Also discover new, non-ignored untracked files\nnpx @alexissliwak/repo-lib push --all\n```\n\nBefore copying, both forms remove library payload that has become tracked and\nprune empty directories. The default form updates existing library payload when\nthe corresponding worktree file still exists; a library file is preserved when\nits worktree counterpart is missing.\n\n`--all` additionally previews and asks before copying new, non-ignored,\nuntracked files. Newly ignored files are not bulk-added and must be selected\nexplicitly with `repo-lib add`.\n\nFor a local-only project, `push` warns that tracked source is not backed up and\nasks for confirmation. If remotes have since been added, it creates a marker\nafter selecting the intended remote when necessary. An existing marker that no\nlonger matches any configured remote is treated as an error.\n\n### `repo-lib pull`\n\nUpdates tracked source and then overlays the current project's library payload:\n\n```sh\nnpx @alexissliwak/repo-lib pull\n```\n\nFor a remote-backed project, `pull` requires:\n\n- a clean tracked worktree;\n- an attached branch with an upstream; and\n- an upstream remote URL matching `remote-repo.txt`.\n\nIt runs a fast-forward-only Git pull. If Git cannot fast-forward, no library\npayload is overlaid. After a successful Git update, files that have become\ntracked are removed from the library, then the remaining library files are\ncopied to the worktree.\n\nDiffering untracked destination files are previewed and require one\nconfirmation. File/directory type conflicts stop the operation safely. If that\nconfirmation is cancelled after Git updated, the Git update remains but no\nlibrary payload is copied.\n\nFor a local-only project, no Git pull is attempted. The command warns that\ntracked source cannot be restored and offers the same payload overlay flow.\n\n### `repo-lib list`\n\nLists the current project's stored payload files in stable, project-relative\norder:\n\n```sh\nnpx @alexissliwak/repo-lib list\n```\n\nThe reserved marker and nested projects are not shown.\n\n### Help and version\n\n```sh\nnpx @alexissliwak/repo-lib --help\nnpx @alexissliwak/repo-lib --version\nnpx @alexissliwak/repo-lib push --help\n```\n\n## Safety behavior\n\n- Git commands are invoked directly without a shell.\n- Copy targets are canonicalized and constrained to the configured roots.\n- Symlinks and junctions are skipped rather than followed.\n- Copies use temporary sibling files and atomic replacement where supported.\n- Tracked payload is removed from the library on every `push` and `pull`.\n- `remote-repo.txt` is metadata only and is never copied into a worktree.\n- New ignored files are copied only when explicitly named with `add`.\n\n`repo-lib` is not a replacement for a secret manager, encryption, access\ncontrols, or a backup of remote Git repositories.\n\n## Exit codes\n\n| Code | Meaning |\n| ---: | --- |\n| `0` | Command succeeded, including a safe no-op. |\n| `1` | Operational failure, such as a Git, filesystem, or configuration error. |\n| `2` | Invalid command-line usage. |\n| `130` | The user cancelled an interactive operation. |\n\n## Development\n\n```sh\ncorepack enable\npnpm install --frozen-lockfile\npnpm run typecheck\npnpm test\npnpm run coverage\npnpm run build\npnpm run pack:verify\n```\n\nTests use isolated real Git repositories and local bare remotes; they do not\nneed network access. Continuous integration runs on Windows and Ubuntu with\nNode.js 22 and 24. The repository pins pnpm through the `packageManager` field;\n`package-lock.json` is intentionally not used.\n\n## Publishing\n\nPublishing is intentionally manual. Before release:\n\n1. Confirm the package name is still available and that the registry account has\n   permission to publish it:\n\n   ```sh\n   pnpm view @alexissliwak/repo-lib name version\n   ```\n\n   An unclaimed name normally returns a registry `E404`; a successful response\n   means the name is already registered and ownership must be verified.\n\n2. Run the complete verification suite:\n\n   ```sh\n   pnpm install --frozen-lockfile\n   pnpm run typecheck\n   pnpm test\n   pnpm run coverage\n   pnpm run build\n   pnpm run pack:verify\n   ```\n\n3. Inspect the generated package archive, then publish publicly:\n\n   ```sh\n   pnpm publish --access public\n   ```\n\nThe npm package should contain only compiled output, this README, the license,\nand package metadata.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"","_rev":"1-36410d8c5095cd941c97d1cede1955b1"}