srcpack 0.3.0 → 1.0.0

package/dist/plan.d.ts

@@ -0,0 +1,64 @@
+import type { BundleResult } from "./bundle.ts";
+import { type BundleConfig } from "./config.ts";
+import { type CapturedPage, type ScreenshotTarget } from "./screenshot.ts";
+/** Where a bundle writes. */
+export interface PlannedBundle {
+    name: string;
+    source: BundleConfig;
+    /** Absolute path of the text output. Absent for a screenshot-only bundle. */
+    text?: {
+        outfile: string;
+    };
+    /** Page to capture into `<dir>/<name>-NN.png`. */
+    images?: {
+        target: ScreenshotTarget;
+        dir: string;
+    };
+}
+/** What a bundle produced, ready to write. */
+export interface ResolvedBundle {
+    plan: PlannedBundle;
+    text?: BundleResult;
+    images?: CapturedPage;
+}
+export interface BundleSelection {
+    /** Bundles this run builds, in the order named or configured. */
+    names: string[];
+    /** On-demand bundles a full run left out. Empty when bundles are named. */
+    skipped: string[];
+}
+/**
+ * Pick the bundles a run builds. Naming a bundle always builds it; a full run
+ * builds everything not marked `onDemand`.
+ */
+export declare function selectBundles(bundles: Record<string, BundleConfig>, requested: string[]): BundleSelection;
+export interface OutputPlan {
+    /** The bundles this run builds, in order. */
+    bundles: PlannedBundle[];
+    /**
+     * Absolute paths srcpack writes, never to be bundled: every configured text
+     * output and every active one, each in lexical and entry spelling. A glob
+     * rooted at a symlink yields lexical paths, one rooted at the real directory
+     * yields physical ones, and either can name a file the previous run wrote.
+     *
+     * Image families need no entry: they always live in outDir, which the CLI
+     * excludes, and when outDir holds the root a PNG is skipped as binary anyway.
+     */
+    ownOutputs: string[];
+}
+/**
+ * Derive where every bundle writes and reject two bundles sharing a file.
+ *
+ * Resolve directory aliases and compare destinations with `pathKey` to prevent
+ * silent overwrites. Text files also collide with numbered images in the same
+ * directory, including their own bundle's images.
+ *
+ * Configured bundles are checked against each other on every run, so a config
+ * error doesn't depend on what was asked for. Active bundles — the ones `active`
+ * names, ad-hoc included — are checked against configured bundles of a
+ * different name: an ad-hoc bundle shadows a configured bundle of its own name
+ * (`--staged` over a `staged` bundle) but never overwrites another's output.
+ * Active bundles need no check among themselves: they are either configured,
+ * and already checked, or a single ad-hoc bundle.
+ */
+export declare function planOutputs(root: string, outDir: string, configured: Record<string, BundleConfig>, active: [name: string, source: BundleConfig][]): Promise<OutputPlan>;

package/dist/screenshot.d.ts

@@ -0,0 +1,113 @@
+import type * as PlaywrightModule from "playwright";
+import type { ScreenshotSource } from "./config.ts";
+/** A capture failure worth a clean message: no Playwright, no page, no browser. */
+export declare class ScreenshotError extends Error {
+    /** Nothing answered at the URL — most often a dev server that isn't running. */
+    readonly unreachable: boolean;
+    constructor(message: string, options?: {
+        unreachable?: boolean;
+    });
+}
+export type Viewport = "desktop" | "mobile";
+/** A screenshot source with its defaults applied. */
+export interface ScreenshotTarget {
+    url: string;
+    viewport: Viewport;
+    hide: string[];
+}
+export declare function toScreenshotTarget(source: ScreenshotSource): ScreenshotTarget;
+/** A vertical region of the page, in CSS px. */
+export interface Slice {
+    y: number;
+    height: number;
+}
+/**
+ * Split a page into the fewest overlapping slices that cover it top to bottom,
+ * each overlapping the next by at least `SLICE_OVERLAP` device px.
+ *
+ * Slices then shrink to share the page evenly rather than staying at the
+ * maximum: a page one pixel taller than a slice becomes two half-page slices,
+ * not two near-identical full ones that spend a model's attention twice.
+ */
+export declare function planSlices(cssHeight: number, dpr: number): Slice[];
+/**
+ * `home-00.png`, `home-01.png`, … Index 0 is the whole page, so filename
+ * order is review order. Padding grows with the highest index so the order
+ * holds past 99.
+ */
+export declare function imageFileName(name: string, index: number, highestIndex: number): string;
+/**
+ * Whether `file` is one of bundle `name`'s numbered images. The suffix is
+ * digits only, so `home-01-02.png` (bundle `home-01`) is never one of `home`'s.
+ *
+ * An exact match, because it decides what stale-image cleanup deletes and
+ * folding could only widen that (ADR 004). To ask whether two spellings
+ * collide, pass `pathKey`s.
+ */
+export declare function isImageOf(name: string, file: string): boolean;
+export type Playwright = Pick<typeof PlaywrightModule, "chromium" | "devices">;
+/** Loads a module by specifier, throwing `MODULE_NOT_FOUND` when absent. */
+export type Require = (id: string) => unknown;
+/**
+ * Load Playwright without bundling it. `require` through `createRequire` keeps
+ * `bun build` from inlining an optional peer that most users never install.
+ */
+export declare function loadPlaywright(root: string, from?: [Require, string][], userAgent?: string | undefined): Playwright;
+/**
+ * Launch Playwright's Chromium, falling back to system Chrome only when the
+ * executable is missing: the browser download is where this flow loses people,
+ * and most developers already have Chrome. Other launch errors stay visible.
+ */
+export declare function launchBrowser(playwright: Playwright, userAgent?: string | undefined): Promise<PlaywrightModule.Browser>;
+/** What a capture produced. Dimensions are the page's, in CSS px. */
+export interface CapturedPage {
+    width: number;
+    height: number;
+    /**
+     * Index 0 is the whole page, 1… the detail slices top to bottom. An index is
+     * carried rather than implied by position, so an omitted overview leaves
+     * `01…` in place instead of renumbering a detail slice into `00`.
+     */
+    images: {
+        index: number;
+        data: Uint8Array;
+    }[];
+}
+/** One browser for a whole run, launched when the first capture needs it. */
+export interface Capturer {
+    capture(target: ScreenshotTarget, warn: (message: string) => void): Promise<CapturedPage>;
+    /** Close the browser, if one was launched. Never throws. */
+    close(): Promise<void>;
+}
+export declare function createCapturer(root: string, load?: () => Playwright): Capturer;
+export interface NetworkWatch {
+    /**
+     * Resolves after the quiet window with nothing in flight, or after `limit`
+     * ms — never longer than the cap.
+     */
+    idle(limit?: number): Promise<void>;
+}
+/** The part of a Playwright page that reports requests. */
+export interface RequestEvents {
+    on(event: "request" | "requestfinished" | "requestfailed", listener: (request: unknown) => void): unknown;
+}
+/**
+ * Track requests from before navigation onward. Not Playwright's `networkidle`
+ * load state: once reached it resolves immediately, so waiting for it after
+ * scrolling misses exactly the requests scrolling started.
+ *
+ * Quiet is measured from the last request event, not sampled: a request that
+ * starts and finishes between two polls still restarts the window.
+ */
+export declare function watchNetwork(page: RequestEvents, { quiet, cap }?: {
+    quiet?: number | undefined;
+    cap?: number | undefined;
+}): NetworkWatch;
+/**
+ * Match install commands to `npm_config_user_agent`, defaulting to npm when
+ * the invoking package manager is unknown.
+ */
+export declare function packageManager(userAgent?: string): {
+    add: string;
+    exec: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srcpack",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Zero-config CLI for bundling code into LLM-optimized context files",
   "keywords": [
     "llm",
@@ -87,9 +87,18 @@
     "picomatch": "^4.0.5",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "playwright": "*"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "@types/picomatch": "^4.0.3",
+    "playwright": "1.63.0",
     "prettier": "^3.9.6",
     "typescript": "^6.0.3",
     "vitepress": "^2.0.0-alpha.19",

package/src/args.ts

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: MIT
+
+import { parseArgs } from "node:util";
+import type { BundleConfig } from "./config.ts";
+
+/** A mistake on the command line: reported without a stack trace. */
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Every option the CLI accepts; `strict` rejects the rest. A typo that gets
+ * quietly dropped is the dangerous kind: `--no-uplaod` uploads, `--dry-rnu`
+ * writes, `--no-emptyOutdir` empties. Same rule as the config — a token that
+ * changes what a run destroys or publishes is never a silent no-op.
+ *
+ * Negatives are declared literally rather than with `allowNegative`, which
+ * negates every boolean and would make `--upload` valid by defining `upload`.
+ */
+const OPTIONS = {
+  staged: { type: "boolean" },
+  dirty: { type: "boolean" },
+  // Valued options are `multiple` so a repeat is seen and rejected rather
+  // than last-one-wins
+  since: { type: "string", multiple: true },
+  screenshot: { type: "string", multiple: true },
+  viewport: { type: "string", multiple: true },
+  "dry-run": { type: "boolean" },
+  emptyOutDir: { type: "boolean" },
+  "no-emptyOutDir": { type: "boolean" },
+  "no-upload": { type: "boolean" },
+} as const;
+
+const AD_HOC_FLAGS = ["staged", "dirty", "since", "screenshot"] as const;
+
+const MISSING_VALUE = {
+  since: "Missing revision: --since <rev> (e.g. --since main)",
+  screenshot:
+    "Missing URL: --screenshot <url> (e.g. --screenshot localhost:5173)",
+  viewport: "Missing viewport: --viewport <desktop|mobile>",
+};
+
+const VIEWPORTS = ["desktop", "mobile"] as const;
+
+/**
+ * Parse everything after `srcpack` except `--help`, `--version` and the
+ * `init`/`login` subcommands, which the CLI handles before this.
+ */
+export function parseCliArgs(argv: string[]): CliArgs {
+  // parseArgs accepts `--` as a terminator even when strict, which would turn
+  // a stray `srcpack --` into a full run that empties and uploads
+  if (argv.includes("--")) throw unknownOption("--");
+
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: OPTIONS,
+      strict: true,
+      allowPositionals: true,
+    });
+  } catch (error) {
+    throw toUsageError(error as NodeJS.ErrnoException);
+  }
+  const { values, positionals } = parsed;
+
+  // Both flags set both values, so parseArgs can't reject this on its own
+  if (values.emptyOutDir && values["no-emptyOutDir"]) {
+    throw new UsageError("Cannot combine --emptyOutDir with --no-emptyOutDir.");
+  }
+
+  const adHocFlags = AD_HOC_FLAGS.filter((flag) => values[flag] !== undefined);
+  if (adHocFlags.length > 1) {
+    throw new UsageError(
+      `Cannot combine ${adHocFlags.map((flag) => `--${flag}`).join(" and ")}.`,
+    );
+  }
+  for (const flag of Object.keys(
+    MISSING_VALUE,
+  ) as (keyof typeof MISSING_VALUE)[]) {
+    const given = values[flag] ?? [];
+    if (given.length > 1) {
+      throw new UsageError(
+        `--${flag} takes one value; got ${given.map((v) => `"${v}"`).join(" and ")}.`,
+      );
+    }
+  }
+  const [viewport] = values.viewport ?? [];
+  if (viewport !== undefined && !values.screenshot) {
+    throw new UsageError("--viewport applies to --screenshot <url>.");
+  }
+  const adHoc = toAdHocBundle(adHocFlags[0], {
+    since: values.since?.[0],
+    screenshot: values.screenshot?.[0],
+    viewport,
+  });
+  if (adHoc && positionals.length) {
+    throw new UsageError(`Cannot combine --${adHoc.name} with named bundles.`);
+  }
+
+  return {
+    bundles: positionals,
+    adHoc,
+    dryRun: values["dry-run"] ?? false,
+    emptyOutDir: values.emptyOutDir
+      ? true
+      : values["no-emptyOutDir"]
+        ? false
+        : undefined,
+    upload: !values["no-upload"],
+  };
+}
+
+function toAdHocBundle(
+  flag: (typeof AD_HOC_FLAGS)[number] | undefined,
+  value: { since?: string; screenshot?: string; viewport?: string },
+): AdHocBundle | null {
+  switch (flag) {
+    case "staged":
+      return { name: "staged", source: ["git:staged"] };
+    case "dirty":
+      return { name: "dirty", source: ["git:dirty"] };
+    case "since": {
+      const rev = value.since;
+      // `--since=` parses as an empty value rather than a missing one
+      if (!rev) throw new UsageError(MISSING_VALUE.since);
+      // A range pins both endpoints, so it would silently drop the uncommitted
+      // work --since promises. Ranges belong in a config `git:` source.
+      if (rev.includes("..")) {
+        throw new UsageError(
+          `--since takes a revision, not a range: "${rev}". Use a git: source in your config for ranges.`,
+        );
+      }
+      // `git diff` can't see untracked files, but a new file written on this
+      // branch is part of "what changed since <rev>"
+      return { name: "since", source: [`git:${rev}`, "git:untracked"] };
+    }
+    case "screenshot": {
+      if (!value.screenshot) throw new UsageError(MISSING_VALUE.screenshot);
+      // Typed at a prompt, `localhost:5173` means http. Config URLs must carry
+      // the scheme, since there they are written once and read by others.
+      // Only a leading scheme counts: `localhost:5173/?next=https://x` has none
+      const url = /^[a-z][a-z\d+.-]*:\/\//i.test(value.screenshot)
+        ? value.screenshot
+        : `http://${value.screenshot}`;
+      if (!/^https?:\/\//i.test(url) || !URL.canParse(url)) {
+        throw new UsageError(
+          `--screenshot takes an http(s) URL, got "${value.screenshot}".`,
+        );
+      }
+      const viewport = value.viewport ?? "desktop";
+      if (!(VIEWPORTS as readonly string[]).includes(viewport)) {
+        throw new UsageError(
+          `--viewport must be "desktop" or "mobile", got "${viewport}".`,
+        );
+      }
+      return {
+        name: "screenshot",
+        source: {
+          screenshot: {
+            url,
+            viewport: viewport as (typeof VIEWPORTS)[number],
+          },
+        },
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+function unknownOption(option: string): UsageError {
+  return new UsageError(
+    `Unknown option: ${option}\nRun \`srcpack --help\` to see the available options.`,
+  );
+}
+
+/**
+ * Translate unknown options and missing values into srcpack usage errors.
+ * Avoid parseArgs suggestions to use `--`, which srcpack rejects.
+ */
+function toUsageError(error: NodeJS.ErrnoException): Error {
+  switch (error.code) {
+    case "ERR_PARSE_ARGS_UNKNOWN_OPTION":
+      return unknownOption(
+        /'([^']+)'/.exec(error.message)?.[1] ?? error.message,
+      );
+    case "ERR_PARSE_ARGS_INVALID_OPTION_VALUE": {
+      // Missing (`--since`) or swallowed by the next flag (`--since -x`)
+      const flag = /^Option '--([\w-]+)/.exec(error.message)?.[1];
+      return new UsageError(
+        flag && Object.hasOwn(MISSING_VALUE, flag)
+          ? MISSING_VALUE[flag as keyof typeof MISSING_VALUE]
+          : error.message,
+      );
+    }
+    default:
+      return error;
+  }
+}

package/src/bundle.ts

@@ -11,6 +11,7 @@ import {
   type BundleConfigInput,
   type LinearSourceInput,
 } from "./config.ts";
+import { pathKey } from "./fs.ts";
 import { isGitSource, resolveGitSource } from "./git.ts";
 import { resolveLinearSource } from "./linear.ts";
 
@@ -330,30 +331,6 @@ function isExternalPattern(pattern: string): boolean {
   return normalized.startsWith("../");
 }
 
-/**
- * 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 function pathKey(path: string): string {
-  return path.normalize("NFC").toLowerCase();
-}
-
 /**
  * Whether a path is one srcpack writes. `outputs` holds absolute paths of
  * files or directories; a directory covers everything beneath it.