@kingkyylian/handoffkit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0
+
+- Initial TypeScript ESM CLI scaffold.
+- Added `handoffkit pack`.
+- Added Markdown and JSON reports.
+- Added git status, recent commit, changed file, diff summary, and optional diff collection.
+- Added instruction file detection with compact redacted previews.
+- Added package manager and verification script detection.
+- Added best-effort secret redaction.
+- Added `pack --since`, `pack --verify`, and `pack --for`.
+- Added `verify`, `risk`, and `resume` commands.
+- Added deterministic risk notes.
+- Added optional `gitleaks` and `secretlint` availability metadata and bounded redacted scan results.
+- Added release checklist documentation and CI package dry-run validation.
+- Added unit and integration tests.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,24 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to a respectful, harassment-free project space.
+
+## Expected Behavior
+
+- Be direct and constructive.
+- Assume good intent, but prioritize clear technical discussion.
+- Keep issues and pull requests focused on the project.
+- Respect maintainer decisions about scope and tradeoffs.
+
+## Unacceptable Behavior
+
+- Harassment, abuse, personal attacks, or discriminatory language.
+- Publishing private information without consent.
+- Repeated off-topic or disruptive comments.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove comments; close issues; block users; or take other reasonable action to protect the project.
+
+Report concerns through GitHub security advisories or by contacting the maintainer.

package/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+Thanks for working on HandoffKit.
+
+## Local Setup
+
+```sh
+pnpm install
+pnpm check
+pnpm pack:dry-run
+```
+
+Node.js 22 or newer is required.
+
+## Development Rules
+
+- Keep the CLI local-first and deterministic.
+- Do not add LLM API calls or telemetry.
+- Add focused tests for behavior changes.
+- Keep generated handoff output redacted by default.
+- Prefer small, readable modules over framework-heavy abstractions.
+
+## Pull Request Checklist
+
+- `pnpm check`
+- `pnpm pack:dry-run`
+- Manual smoke test: `pnpm dev pack --goal "Make your own goal"`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyylian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# HandoffKit
+
+[![CI](https://github.com/kingkyylian/handoffkit/actions/workflows/ci.yml/badge.svg)](https://github.com/kingkyylian/handoffkit/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@kingkyylian/handoffkit.svg)](https://www.npmjs.com/package/@kingkyylian/handoffkit)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-43853d.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+HandoffKit is the clean handoff packet for interrupted AI coding sessions.
+
+It turns messy AI-assisted coding work into a safe resume packet you can paste into Codex, Claude Code, Cursor, Gemini, ChatGPT, or another agent. It is a local-first TypeScript CLI: it inspects the current git repository, summarizes the live branch state, detects agent instruction files, finds package verification scripts, redacts likely secrets, and prints compact Markdown by default. It does not call any LLM API.
+
+## Why It Exists
+
+AI coding sessions get interrupted: context windows fill up, tools change, laptops sleep, a model gets stuck, or work needs to move from Claude Code to Codex or Cursor. The hard part is not feeding an entire repo to an agent. The hard part is explaining what happened on this branch and what the next agent should do.
+
+HandoffKit creates a deterministic handoff packet with the pieces another assistant needs first:
+
+- current branch and git status
+- recent commits
+- staged and unstaged diff summaries
+- changed file list
+- detected instruction files such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules`, and `.github/copilot-instructions.md`, with compact redacted previews
+- package manager and common verification scripts from `package.json`
+- best-effort redaction for likely secrets
+
+## Positioning
+
+HandoffKit is not a repo ingestion tool. It is not trying to replace Repomix, Gitingest, or long-lived repo instruction tools.
+
+Its job is narrower: capture the live state of an interrupted AI coding session so another agent can resume without guessing.
+
+## HandoffKit vs. Repo Instruction Tools
+
+Repo instruction tools such as AgentFit help shape reusable project guidance for AI agents. HandoffKit has a different job: it captures the live state of a coding session right now.
+
+Use repo instruction tools to maintain durable agent rules. Use HandoffKit when you need to hand off an in-progress branch, debugging session, or partially completed change to another assistant without pasting raw diffs and secrets by hand.
+
+## Current MVP
+
+The first release focuses on the minimum useful handoff:
+
+- local git state
+- changed files
+- recent commits
+- diff summaries and optional patches
+- agent instruction file previews
+- package verification scripts
+- best-effort secret redaction
+
+It is useful today, but the goal is to become more than a prettier `git status`. See [ROADMAP.md](ROADMAP.md) for the next features that should make HandoffKit harder to replace with a manual paste.
+
+## Install
+
+Run without installing:
+
+```sh
+pnpm dlx @kingkyylian/handoffkit pack --goal "Make your own goal"
+```
+
+Or install it globally:
+
+```sh
+pnpm add -g @kingkyylian/handoffkit
+```
+
+For local development:
+
+```sh
+pnpm install
+pnpm build
+```
+
+Node.js 22 or newer is required.
+
+## Usage
+
+From inside a git repository:
+
+```sh
+handoffkit pack --goal "Make your own goal"
+```
+
+Focus on the branch delta since a base ref:
+
+```sh
+handoffkit pack --since main --goal "Continue this branch"
+```
+
+Run safe verification scripts and include the result:
+
+```sh
+handoffkit pack --verify --goal "Fix remaining failures"
+```
+
+Run optional local secret scanners and include bounded redacted results:
+
+```sh
+handoffkit pack --scan-secrets --goal "Review before handoff"
+```
+
+Optimize the packet for a target agent:
+
+```sh
+handoffkit pack --for codex --goal "Resume implementation"
+```
+
+During development:
+
+```sh
+pnpm dev pack --goal "Make your own goal"
+```
+
+Write to a file:
+
+```sh
+handoffkit pack --goal "Finish the CLI MVP" --output handoff.md
+```
+
+JSON output:
+
+```sh
+handoffkit pack --goal "Review this branch" --format json
+```
+
+Include full patch text:
+
+```sh
+handoffkit pack --goal "Continue implementation" --include-diff
+```
+
+Omit diff summaries and patches:
+
+```sh
+handoffkit pack --goal "Summarize repo state" --no-diff
+```
+
+Set a rough Markdown token budget:
+
+```sh
+handoffkit pack --goal "Prepare a compact handoff" --budget 3000
+```
+
+Run verification directly:
+
+```sh
+handoffkit verify
+```
+
+Inspect deterministic risk notes:
+
+```sh
+handoffkit risk
+```
+
+Run optional local secret scanners directly:
+
+```sh
+handoffkit scan-secrets
+```
+
+Resume from a previous handoff or transcript:
+
+```sh
+handoffkit resume previous-handoff.md --goal "Continue from here"
+```
+
+## CLI Options
+
+| Option | Description |
+| --- | --- |
+| `--goal <text>` | The handoff goal to place at the top of the packet. |
+| `--output <path>` | Write the packet to a file instead of stdout. |
+| `--format markdown\|json` | Render Markdown or JSON. Defaults to Markdown. |
+| `--for generic\|codex\|claude\|cursor` | Tune the packet heading and prompt shape for a target agent. |
+| `--budget <tokens>` | Rough Markdown token budget. Defaults to `4000`. |
+| `--since <ref>` | Focus committed branch delta on a base ref such as `main`. |
+| `--verify` | Run safe verification scripts and include results in the packet. |
+| `--scan-secrets` | Run optional local secret scanners and include bounded redacted results. |
+| `--include-diff` | Include full tracked patches and bounded untracked previews. |
+| `--no-diff` | Omit diff summaries and full patches. |
+
+## What Gets Collected
+
+HandoffKit reads local git and filesystem metadata from the current repository:
+
+- branch, status, recent commits, changed files, and diff summaries
+- full tracked patch text only when `--include-diff` is used
+- untracked file names in summaries, and untracked file preview content only when `--include-diff` is used
+- compact previews of detected instruction files
+- package manager and verification scripts from the root `package.json`
+- optional verification results when `--verify` is used
+- deterministic risk notes from changed file paths
+- optional secret scanner availability for `gitleaks` and `secretlint`
+- bounded, redacted secret scan results when `--scan-secrets` is used
+
+## What Never Happens
+
+- No LLM API calls.
+- No network requests from the CLI.
+- No git writes, commits, staging, or branch changes.
+- No files are written unless `--output` is provided.
+
+## Development
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+pnpm check
+pnpm pack:dry-run
+```
+
+## Release
+
+Releases are manual and should happen only after CI, package dry-run, and install smoke tests pass. The preferred path is the GitHub `Release` workflow with an `NPM_TOKEN` repository secret so npm provenance is attached to the published package.
+
+See [docs/RELEASE.md](docs/RELEASE.md) for the release checklist.
+
+## Security Model
+
+HandoffKit is local-first and deterministic. It reads local git and filesystem state, renders a report, and redacts likely secrets from generated output. Redaction is best effort, so review packets before pasting them into a third-party tool.
+
+When `--scan-secrets` is used, HandoffKit runs installed local scanners only. It does not install scanners, send code to a service, or fail when `gitleaks` or `secretlint` is missing.
+
+## License
+
+MIT

package/ROADMAP.md

@@ -0,0 +1,109 @@
+# Roadmap
+
+HandoffKit is focused on one niche: clean handoff and resume packets for interrupted AI coding sessions.
+
+It should not become a generic repo-to-context dumper. Existing tools already cover that space well. The roadmap below prioritizes features that make handoff quality better than a manual paste.
+
+## Implemented MVP Surface
+
+These are implemented as local-first deterministic features:
+
+### `handoffkit pack --since <ref>`
+
+Summarize the meaningful branch delta relative to a base ref such as `main`:
+
+```sh
+handoffkit pack --since main --goal "Continue this branch"
+```
+
+Expected behavior:
+
+- compare current branch against the base ref
+- include changed files and commits only from the branch delta
+- reduce noise from unrelated working tree history
+- keep deterministic local output
+
+### `handoffkit pack --verify` and `handoffkit verify`
+
+Run detected verification commands and include the result in the packet:
+
+```sh
+handoffkit verify
+handoffkit pack --goal "Fix remaining failures"
+```
+
+Expected behavior:
+
+- choose safe scripts such as `typecheck`, `lint`, `test`, `build`
+- capture command, exit code, duration, and tail output
+- avoid running arbitrary destructive scripts
+- include verification in a handoff packet when `pack --verify` is used
+
+### Agent-Specific Output
+
+Optimize handoff shape for target agents:
+
+```sh
+handoffkit pack --for codex
+handoffkit pack --for claude
+handoffkit pack --for cursor
+```
+
+Expected behavior:
+
+- keep the same source facts
+- adjust section order, headings, and action prompts for the target tool
+- avoid tool-specific claims that cannot be verified locally
+
+### `handoffkit risk`
+
+Produce deterministic risk notes from changed files and package signals:
+
+```sh
+handoffkit risk
+```
+
+Expected behavior:
+
+- flag likely test gaps
+- note config, auth, security, migration, packaging, or CI-sensitive changes
+- stay rule-based unless an explicit local model integration is added later
+
+### `handoffkit resume`
+
+Generate a fresh packet from a previous handoff, transcript, or interrupted session notes:
+
+```sh
+handoffkit resume previous-handoff.md --goal "Continue from here"
+```
+
+Expected behavior:
+
+- extract prior goal, completed work, remaining tasks, and verification state
+- merge with current git state
+- produce a clean next-agent packet
+
+### Stronger Secret Scanning
+
+Regex redaction remains the default. HandoffKit detects optional local scanners and can run bounded local scans with `pack --scan-secrets` or `scan-secrets`:
+
+- `secretlint`
+- `gitleaks`
+- provider-specific token patterns
+
+Scan results are bounded and redacted before rendering.
+
+## Next Up
+
+- Add scanner-specific installation guidance and config discovery.
+- Make `risk` rules richer by mapping changed files to common failure modes.
+- Improve `--for` formats beyond headings, with agent-specific action prompts.
+- Add transcript parsers for Claude Code, Codex, Cursor, and Gemini exports.
+- Add a stable `.handoffkit` cache format for verification and resume artifacts.
+
+## Non-Goals
+
+- No LLM API calls in the core CLI.
+- No telemetry.
+- No generic full-repo context dumping as the primary product.
+- No git writes unless a command explicitly asks for an output file or cache artifact.

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+HandoffKit is designed to create safe handoff packets, but redaction is best effort.
+
+## Reporting a Vulnerability
+
+Please open a private security advisory on GitHub or contact the maintainer directly. Do not publish working exploit details before there is a fix or documented mitigation.
+
+## Security Boundaries
+
+- The CLI does not call LLM APIs.
+- The CLI should not make network requests.
+- The CLI should not modify git state.
+- Generated output is redacted after rendering, before stdout or file writes.
+
+Review generated packets before pasting them into third-party tools, especially when using `--include-diff`.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node