raindrop-cli 0.1.0 → 0.1.1

package/README.md

@@ -339,14 +339,40 @@ src/
 
 ## Releasing
 
-For maintainers publishing a new version to npm.
+For maintainers publishing a new version to npm. We use [release-it](https://github.com/release-it/release-it) to automate the release process.
 
 ### Prerequisites
 
 - Push access to the repository
-- npm account with publish rights to `raindrop-cli`
-- Logged in to npm (`npm whoami` to verify)
+- npm account with publish rights to `raindrop-cli` (`npm whoami` to verify)
 - ggshield installed and authenticated (`ggshield auth status`)
+- `GITHUB_TOKEN` environment variable set (for creating GitHub releases)
+
+#### Getting a GitHub Token
+
+1. Go to [GitHub Settings → Tokens](https://github.com/settings/tokens?type=beta) (fine-grained)
+2. Click **Generate new token**
+3. Set expiration and select **Only select repositories** → `raindrop-cli`
+4. Under **Repository permissions**, set **Contents** to **Read and write**
+5. Generate and export: `export GITHUB_TOKEN=github_pat_xxxx`
+
+Or use a [classic token](https://github.com/settings/tokens/new) with the `repo` scope (broader access).
+
+### Before You Release
+
+Update `CHANGELOG.md` with your changes under the `[Unreleased]` section:
+
+```markdown
+## [Unreleased]
+
+### Added
+- New feature X
+
+### Fixed
+- Bug Y
+```
+
+The release process will automatically move these entries to the new version section.
 
 ### Release Process
 
@@ -355,47 +381,56 @@ For maintainers publishing a new version to npm.
 git checkout main
 git pull
 
-# 2. Update CHANGELOG.md
-# - Move items from "Unreleased" to new version section
-# - Set the release date (e.g., ## [0.2.0] - 2026-01-15)
+# 2. Preview what will happen (recommended first time)
+bun run release:dry
 
-# 3. Commit the changelog
-git add CHANGELOG.md
-git commit -m "chore: update changelog for vX.Y.Z"
+# 3. Run the release
+bun run release
+```
 
-# 4. Bump version (creates commit + git tag automatically)
-npm version patch  # or: minor, major
-# This updates package.json and creates a vX.Y.Z tag
+The interactive prompt will ask you to select the version bump (patch/minor/major). Then release-it will:
 
-# 5. Dry run to verify package contents
-npm publish --dry-run --access public
+1. **Verify** — runs tests, lint, typecheck, format
+2. **Bump version** — updates `package.json`
+3. **Update changelog** — moves "Unreleased" items to new version section with date
+4. **Build** — compiles to `dist/`
+5. **Commit** — creates "chore: release vX.Y.Z" commit
+6. **Tag** — creates `vX.Y.Z` git tag
+7. **Secret scan** — ggshield scans for leaked secrets
+8. **Publish to npm** — uploads package
+9. **Push** — pushes commit and tag to GitHub
+10. **GitHub Release** — creates release with changelog notes
 
-# 6. Publish to npm
-npm publish --access public
+### Manual Steps (if needed)
 
-# 7. Push commits and tags to GitHub
-git push && git push --tags
+If you need to skip certain steps or recover from a partial release:
 
-# 8. Verify installation works
-npm info raindrop-cli
-npx raindrop-cli@latest --version
-```
+```bash
+# Skip npm publish (e.g., if it succeeded but git push failed)
+bun run release -- --no-npm
 
-### What Happens During Publish
+# Skip GitHub release
+bun run release -- --no-github
 
-The `prepublishOnly` script runs automatically before upload:
+# Specific version (skip prompt)
+bun run release -- 1.2.3
 
-1. **Verify** — runs tests, lint, typecheck, format
-2. **Build** — compiles to `dist/`
-3. **Secret scan** — ggshield scans source and `dist/` for leaked secrets
-4. **Package** — creates tarball with only: `dist/*`, `README.md`, `LICENSE`, `package.json`
+# Pre-release
+bun run release -- --preRelease=beta
+```
 
-No need to run `bun run build` manually — it's all handled automatically.
+### Verify After Release
+
+```bash
+npm info raindrop-cli
+npx raindrop-cli@latest --version
+```
 
 ### Notes
 
-- **Immutable** — published versions cannot be changed, only deprecated
-- **Tags** — `npm version` creates the git tag; just remember to `git push --tags`
+- **Immutable** — published npm versions cannot be changed, only deprecated
+- **Clean working directory required** — commit or stash changes before releasing
+- **Main branch only** — releases must be from the `main` branch
 - **Secrets** — publish will fail if ggshield detects secrets in the bundle
 
 ## Contributing

package/dist/cli/context.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CLI context module - consolidated global state for CLI operations.
+ *
+ * Creates a CliContext object from argv and environment, providing:
+ * - Output configuration (format, color, verbosity)
+ * - TTY detection
+ * - Color functions that respect color settings
+ * - Prefixes for different message types
+ *
+ * @example
+ * ```ts
+ * import { createContext } from './cli/context.js';
+ *
+ * const ctx = createContext(process.argv.slice(2), process.env);
+ * console.log(ctx.colors.green('Success!'));
+ * ```
+ */
+import type { OutputFormat } from "../types/index.js";
+export type OutputConfig = {
+    format: OutputFormat | undefined;
+    color: boolean;
+    verbose: boolean;
+    debug: boolean;
+    quiet: boolean;
+};
+export type CliContext = {
+    isTty: boolean;
+    output: OutputConfig;
+    colors: {
+        bold: (t: string) => string;
+        dim: (t: string) => string;
+        cyan: (t: string) => string;
+        yellow: (t: string) => string;
+        green: (t: string) => string;
+        red: (t: string) => string;
+    };
+    prefix: {
+        ok: string;
+        warn: string;
+        err: string;
+        info: string;
+    };
+};
+/**
+ * Create CLI context from argv and environment.
+ *
+ * @param argv - Command line arguments (without node/script path)
+ * @param env - Environment variables
+ * @param isTty - Whether stdout is a TTY (passed explicitly for testability)
+ */
+export declare function createContext(argv: string[], env: Record<string, string | undefined>, isTty?: boolean): CliContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/cli/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/cli/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC5B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC9B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC7B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;KAC5B,CAAC;IACF,MAAM,EAAE;QACN,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,KAAK,GAAE,OAAuC,GAC7C,UAAU,CAuCZ"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+export { createContext, type CliContext, type OutputConfig } from "./context.js";
+export { createProgram } from "./program.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/cli/program.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Commander program setup - creates and configures the CLI program.
+ *
+ * This module:
+ * - Creates the root Command program
+ * - Registers all global options
+ * - Sets up the preAction hook for global option handling
+ * - Registers all commands and shortcuts
+ * - Configures styled help output
+ */
+import { Command } from "commander";
+import type { CliContext } from "./context.js";
+/**
+ * Create and configure the Commander program.
+ *
+ * @param ctx - CLI context with output configuration
+ * @returns Configured Commander program ready for parsing
+ */
+export declare function createProgram(ctx: CliContext): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/cli/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAA0B,MAAM,WAAW,CAAC;AAI5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA+K/C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CA8ItD"}

package/dist/cli-main.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI main orchestration - error handling and stream setup.
+ *
+ * This layer:
+ * - Sets up output streams (for testability)
+ * - Handles EPIPE errors gracefully (pipe closed by consumer)
+ * - Handles top-level errors with proper formatting
+ * - Coordinates between the thin shell (cli.ts) and core logic (run.ts)
+ */
+/**
+ * Handle EPIPE errors gracefully (pipe closed by consumer like head/grep).
+ * This is normal when piping to commands that don't consume all output.
+ */
+export declare function handlePipeErrors(stream: NodeJS.WritableStream, exit: (code: number) => void): void;
+export type CliMainArgs = {
+    argv: string[];
+    env: Record<string, string | undefined>;
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+    exit: (code: number) => void;
+    setExitCode: (code: number) => void;
+};
+export declare function runCliMain(args: CliMainArgs): Promise<void>;
+//# sourceMappingURL=cli-main.d.ts.map

package/dist/cli-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-main.d.ts","sourceRoot":"","sources":["../src/cli-main.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,cAAc,EAC7B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3B,IAAI,CAQN;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCjE"}

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point - thin shell that injects process.* dependencies.
+ *
+ * This is the executable entry point (package.json bin).
+ * All it does is inject process.* dependencies and call runCliMain().
+ *
+ * Why this thin layer?
+ * - Makes the CLI testable without spawning subprocesses
+ * - Keeps process.* access in one place
+ * - Enables dependency injection for streams, exit, etc.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}