srcpack 0.3.0 → 1.0.0

package/README.md

@@ -10,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
@@ -57,7 +57,7 @@ Or add to `package.json`:
 | `bundles`     | —          | Named bundle definitions              |
 | `upload`      | —          | Upload destination(s)                 |
 
-\*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.
+\*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
 
@@ -78,9 +78,11 @@ Or add to `package.json`:
 {
   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
 }
 ```
 
@@ -88,6 +90,8 @@ 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`.
@@ -104,6 +108,18 @@ bundles: {
 
 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:
@@ -154,14 +170,15 @@ import { utils } from "./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 writing
-npx srcpack --no-emptyOutDir # Keep existing files in output directory
+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

@@ -21,27 +21,6 @@ export interface BundleResult {
     content: string;
     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