srcpack 0.2.0 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # Srcpack
 
+[![npm version](https://img.shields.io/npm/v/srcpack)](https://www.npmjs.com/package/srcpack) [![npm downloads](https://img.shields.io/npm/dm/srcpack)](https://www.npmjs.com/package/srcpack) [![CI](https://img.shields.io/github/actions/workflow/status/kriasoft/srcpack/ci.yml?branch=main&label=CI)](https://github.com/kriasoft/srcpack/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/srcpack)](./LICENSE) [![Discord](https://img.shields.io/discord/643523529131950086?label=Discord&logo=discord&logoColor=white)](https://discord.com/invite/aG83xEb6RX)
+
 Zero-config CLI for bundling code into LLM-optimized context files.
 
 **Requirements:** Node.js 22.18+ or Bun
@@ -48,14 +50,14 @@ Or add to `package.json`:
 
 ### Options
 
-| Option        | Default    | Description                            |
-| ------------- | ---------- | -------------------------------------- |
-| `outDir`      | `.srcpack` | Output directory for bundles           |
-| `emptyOutDir` | `true`\*   | Empty output directory before bundling |
-| `bundles`     | —          | Named bundles with glob patterns       |
-| `upload`      | —          | Upload destination(s)                  |
+| Option        | Default    | Description                           |
+| ------------- | ---------- | ------------------------------------- |
+| `outDir`      | `.srcpack` | Output directory for bundles          |
+| `emptyOutDir` | `true`\*   | Empty output directory before writing |
+| `bundles`     | —          | Named bundle definitions              |
+| `upload`      | —          | Upload destination(s)                 |
 
-\*`emptyOutDir` defaults to `true` when `outDir` is inside project root. When `outDir` is outside root, a warning is emitted unless explicitly set. Emptying happens only on a full run, so `npx srcpack web` leaves other bundles in place.
+\*Only the default `.srcpack` is emptied automatically — it's srcpack's directory by convention. Any other `outDir` needs an explicit `emptyOutDir: true`, so `outDir: "src"` can't quietly delete your sources. Emptying also happens only on a full run, so `npx srcpack web` leaves other bundles in place.
 
 ### Bundle Config
 
@@ -75,6 +77,7 @@ Or add to `package.json`:
 // Full options
 {
   include: "src/**/*",
+  linear: { team: "ENG" },             // Linear issues as virtual files
   outfile: "~/Downloads/bundle.txt",   // custom output path
   index: true,                         // include index header (default)
   prompt: "./prompts/review.md"        // prepend from file (or inline text)
@@ -85,6 +88,22 @@ Patterns follow glob syntax. Prefix with `!` to exclude, `+` to force-include (b
 
 A pattern can also name a set of changed files: `git:staged`, `git:unstaged`, `git:untracked`, `git:dirty`, or `git:<rev>` (e.g. `git:main`, `git:HEAD~3`). Deleted files are skipped, and `git:<rev>` compares against the merge base so a stale branch still reports only your own changes. See [Git sources](https://kriasoft.com/srcpack/configuration#git-sources-git-prefix).
 
+### Linear Issues
+
+A bundle can include [Linear](https://linear.app) issues next to your code. Each issue becomes a virtual file at `linear/issues/ENG-123.md`, so it gets its own index entry and line range — letting you ask whether `[4] src/board.ts` actually implements `[2] ENG-123`.
+
+```typescript
+bundles: {
+  backlog: { linear: "ENG" },                       // non-terminal issues, team ENG
+  planning: {
+    include: ["docs/**/*.md"],
+    linear: { team: "ENG", project: "Roadmap" },    // scoped to one project
+  },
+}
+```
+
+Authentication reads `LINEAR_API_KEY` from the environment (Linear → Settings → Security & access → Personal API keys), never from the config file. `team` is required, completed/canceled/duplicate issues are excluded by default, and issues obey `!` exclusions like any other entry. See [Linear issues](https://kriasoft.com/srcpack/configuration#linear-issues).
+
 ### Google Drive Upload
 
 To upload bundles to Google Drive, add OAuth credentials to your config:
@@ -115,16 +134,16 @@ export default defineConfig({
 
 ```text
 # Index (3 files)
-# [1]   src/index.ts  L1-L42 (42 lines)
-# [2]   src/utils.ts  L43-L89 (47 lines)
-# [3]   src/api.ts    L90-L150 (61 lines)
+# [1]   src/api.ts  L7-L67 (61 lines)
+# [2]   src/index.ts  L69-L110 (42 lines)
+# [3]   src/utils.ts  L112-L158 (47 lines)
 
-#==> [1] src/index.ts <==
-import { utils } from "./utils";
+#==> [1] src/api.ts <==
+export async function fetchBoard() {
 ...
 
-#==> [2] src/utils.ts <==
-export function utils() {
+#==> [2] src/index.ts <==
+import { utils } from "./utils";
 ...
 ```
 
@@ -141,7 +160,7 @@ npx srcpack --staged        # Bundle staged changes (no config needed)
 npx srcpack --dirty         # Bundle staged + unstaged + untracked
 npx srcpack --since main    # Bundle changes since main
 npx srcpack --dry-run       # Preview without writing files
-npx srcpack --emptyOutDir   # Empty output directory before bundling
+npx srcpack --emptyOutDir   # Empty output directory before writing
 npx srcpack --no-emptyOutDir # Keep existing files in output directory
 npx srcpack --no-upload     # Bundle only, skip upload
 npx srcpack init            # Interactive config setup

package/dist/bundle.d.ts

@@ -1,5 +1,17 @@
 import { type BundleConfigInput } from "./config.ts";
-export interface FileEntry {
+/**
+ * One bundle member, before its content is laid out.
+ *
+ * `content` present means the entry is virtual — produced by a non-filesystem
+ * source such as Linear — and its `path` is synthetic. Absent means an ordinary
+ * file, read from disk at bundle time.
+ */
+export interface Entry {
+    path: string;
+    content?: string;
+}
+/** One line of the bundle index — a file or a virtual entry, once laid out. */
+export interface IndexEntry {
     path: string;
     lines: number;
     startLine: number;
@@ -7,8 +19,29 @@ export interface FileEntry {
 }
 export interface BundleResult {
     content: string;
-    index: FileEntry[];
+    index: IndexEntry[];
 }
+/**
+ * The key two paths are compared by: canonical spelling, then case folded, on
+ * every platform. A case-insensitive filesystem — the default on macOS and
+ * Windows — treats `Context.txt` and `context.txt` as one directory entry, and
+ * APFS additionally folds Unicode normalisation, so `Café.txt` written as
+ * precomposed U+00E9 and as `e` plus U+0301 is also one entry. Normalising
+ * before folding is what makes the comparison sound: equal inputs stay equal
+ * afterwards whether or not case folding preserves normalisation. `realpath`
+ * resolves
+ * an existing component to its on-disk spelling, but that doesn't cover these:
+ * an output not yet written has no on-disk spelling, and the destination entry
+ * is deliberately left unresolved so `rename` replaces a symlink rather than
+ * following it. A config that works in Linux CI and loses a bundle on the
+ * author's laptop is worse than one rejected everywhere, so the rule is the
+ * same on every platform rather than keyed to the filesystem under it.
+ *
+ * Comparison only. Paths used for I/O keep their original spelling, and
+ * ownership stays an exact match: folding there could only widen what srcpack
+ * deletes, which is the one direction that must never be widened by a guess.
+ */
+export declare function pathKey(path: string): string;
 /**
  * Resolve bundle config to a list of file paths.
  * - Regular patterns respect .gitignore
@@ -23,6 +56,15 @@ export interface BundleResult {
  * output, nesting it one level deeper every time.
  */
 export declare function resolvePatterns(config: BundleConfigInput, cwd: string, outputs?: string[]): Promise<string[]>;
+/**
+ * Resolve every source a bundle declares into a sorted entry list.
+ *
+ * Filesystem and `git:` sources produce paths ({@link resolvePatterns}, which
+ * never touches the network); `linear` produces virtual entries carrying their
+ * own content. Both then meet the same rules — `!` exclusions apply uniformly,
+ * and the result is sorted by path so bundles stay deterministic.
+ */
+export declare function resolveEntries(config: BundleConfigInput, cwd: string, outputs?: string[]): Promise<Entry[]>;
 /**
  * Format the index header block.
  * Format designed for LLM context files (ChatGPT, Grok, Gemini):
@@ -30,17 +72,17 @@ export declare function resolvePatterns(config: BundleConfigInput, cwd: string,
  * - ASCII-only characters for broad compatibility
  * - Line locations that point to actual file content
  */
-export declare function formatIndex(index: FileEntry[]): string;
+export declare function formatIndex(index: IndexEntry[]): string;
 export interface BundleOptions {
     includeIndex?: boolean;
     prompt?: string;
 }
 /**
- * Create a bundle from a list of files.
+ * Create a bundle from a list of entries.
  * Line numbers in the index point to the first line of actual file content,
  * not to the separator line.
  */
-export declare function createBundle(files: string[], cwd: string, options?: BundleOptions): Promise<BundleResult>;
+export declare function createBundle(entries: Entry[], cwd: string, options?: BundleOptions): Promise<BundleResult>;
 /**
  * Bundle one config entry. `outputs` lists absolute paths srcpack writes,
  * which are never bundled — see {@link resolvePatterns}.