srcpack 0.2.0 → 1.0.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
@@ -8,7 +10,7 @@ Zero-config CLI for bundling code into LLM-optimized context files.
 
 ```bash
 npx srcpack init         # Create config interactively
-npx srcpack              # Bundle all
+npx srcpack              # Bundle all except on-demand
 ```
 
 ## Why
@@ -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. Named runs (`npx srcpack web`) never empty it, so other bundles stay in place.
 
 ### Bundle Config
 
@@ -75,9 +77,12 @@ Or add to `package.json`:
 // Full options
 {
   include: "src/**/*",
+  linear: { team: "ENG" },             // Linear issues as virtual files
+  screenshot: "http://localhost:5173", // rendered page as numbered PNGs
   outfile: "~/Downloads/bundle.txt",   // custom output path
   index: true,                         // include index header (default)
-  prompt: "./prompts/review.md"        // prepend from file (or inline text)
+  prompt: "./prompts/review.md",       // prepend from file (or inline text)
+  onDemand: true                       // build only when named
 }
 ```
 
@@ -85,6 +90,36 @@ 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).
 
+A full run skips bundles marked `onDemand: true`; name them explicitly to build them. Emptying `outDir` still removes their previous output there. See [On-Demand Bundles](https://kriasoft.com/srcpack/configuration#on-demand-bundles).
+
+### 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).
+
+### Screenshots
+
+A bundle can capture a rendered page as PNGs, with overlapping detail slices for tall pages. Srcpack scrolls to load lazy content before capture and hides Astro and Nuxt dev toolbars.
+
+```typescript
+bundles: {
+  home: { screenshot: "http://localhost:5173/", onDemand: true },
+}
+```
+
+`npx srcpack home` writes PNGs to `.srcpack`: `home-00.png` is the whole page when available; tall pages also get `home-01.png`, `home-02.png`, … detail slices. Attach them in filename order. Images stay local, even with upload configured. For a one-off, no config is needed: `npx srcpack --screenshot localhost:5173 --viewport mobile`. See [Screenshots](https://kriasoft.com/srcpack/configuration#screenshots) for Playwright and browser setup.
+
 ### Google Drive Upload
 
 To upload bundles to Google Drive, add OAuth credentials to your config:
@@ -115,16 +150,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";
 ...
 ```
 
@@ -135,14 +170,15 @@ export function utils() {
 ## CLI
 
 ```bash
-npx srcpack                 # Bundle all, upload if configured
+npx srcpack                 # Bundle all except on-demand, upload if configured
 npx srcpack web api         # Bundle specific bundles only
 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 --screenshot localhost:5173 # Capture a page as PNGs
 npx srcpack --dry-run       # Preview without writing files
-npx srcpack --emptyOutDir   # Empty output directory before bundling
-npx srcpack --no-emptyOutDir # Keep existing files in output directory
+npx srcpack --emptyOutDir   # Empty output directory before writing
+npx srcpack --no-emptyOutDir # Skip clearing the output directory
 npx srcpack --no-upload     # Bundle only, skip upload
 npx srcpack init            # Interactive config setup
 npx srcpack login           # Authenticate with Google Drive

package/dist/args.d.ts

@@ -0,0 +1,26 @@
+import type { BundleConfig } from "./config.ts";
+/** A mistake on the command line: reported without a stack trace. */
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+/**
+ * One-off bundle from a `git:` source or a URL; no config file required.
+ */
+export interface AdHocBundle {
+    name: string;
+    source: BundleConfig;
+}
+export interface CliArgs {
+    /** Bundle names in input order. Empty for full and ad-hoc runs. */
+    bundles: string[];
+    adHoc: AdHocBundle | null;
+    dryRun: boolean;
+    /** Explicit CLI override; `undefined` lets the CLI apply config and run defaults. */
+    emptyOutDir: boolean | undefined;
+    upload: boolean;
+}
+/**
+ * Parse everything after `srcpack` except `--help`, `--version` and the
+ * `init`/`login` subcommands, which the CLI handles before this.
+ */
+export declare function parseCliArgs(argv: string[]): CliArgs;

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,7 +19,7 @@ export interface FileEntry {
 }
 export interface BundleResult {
     content: string;
-    index: FileEntry[];
+    index: IndexEntry[];
 }
 /**
  * Resolve bundle config to a list of file paths.
@@ -23,6 +35,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 +51,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}.