srcpack 0.3.0 → 1.0.0

package/src/config.ts

@@ -77,6 +77,45 @@ const LinearSourceSchema = z.union([
   }),
 ]);
 
+/**
+ * An absolute http(s) URL. A scheme-less `localhost:5173` is called out by
+ * name: `URL` would otherwise parse it as protocol `localhost:`.
+ */
+const HttpUrlSchema = z.string().superRefine((value, ctx) => {
+  if (!value.includes("://")) {
+    ctx.addIssue({
+      code: "custom",
+      message: 'URL needs a scheme, e.g. "http://localhost:5173/"',
+    });
+  } else if (!/^https?:\/\//i.test(value) || !URL.canParse(value)) {
+    ctx.addIssue({ code: "custom", message: "Expected an http(s) URL" });
+  }
+});
+
+/**
+ * A rendered page as numbered PNGs in `outDir`, independent of the text
+ * output path. See ADR 006 for why it is a separate source key.
+ *
+ * @example
+ * ```ts
+ * bundles: {
+ *   home: { screenshot: "http://localhost:5173/", onDemand: true },
+ *   phone: { screenshot: { url: "http://localhost:5173/", viewport: "mobile" } },
+ * }
+ * ```
+ */
+const ScreenshotSourceSchema = z.union([
+  /** Shorthand for `{ url: "<url>" }`. */
+  HttpUrlSchema,
+  z.strictObject({
+    url: HttpUrlSchema,
+    /** Defaults to "desktop". */
+    viewport: z.enum(["desktop", "mobile"]).optional(),
+    /** CSS selectors hidden during capture: cookie banners, chat widgets. */
+    hide: z.array(z.string().min(1)).optional(),
+  }),
+]);
+
 /**
  * Bundle configuration. Accepts a string pattern, array of patterns, or object.
  * Patterns prefixed with `!` are exclusions. Patterns prefixed with `+` force
@@ -86,7 +125,8 @@ const LinearSourceSchema = z.union([
  * `git:unstaged`, `git:untracked`, `git:dirty`, or `git:<rev>` (e.g.
  * `git:main`, `git:HEAD~3`).
  *
- * The object form takes files (`include`), Linear issues (`linear`), or both.
+ * The object form takes files (`include`), Linear issues (`linear`), page
+ * screenshots (`screenshot`), or any combination.
  *
  * @example
  * ```ts
@@ -105,15 +145,46 @@ const BundleConfigSchema = z.union([
       include: PatternsSchema.optional(),
       /** Linear issues to include in the bundle. */
       linear: LinearSourceSchema.optional(),
+      /** Page to capture as numbered PNGs in `outDir`. */
+      screenshot: ScreenshotSourceSchema.optional(),
       /** Custom output file path. Defaults to `<outDir>/<bundleName>.txt`. */
       outfile: z.string().min(1).optional(),
-      /** Include file index header in output. Defaults to true. */
-      index: z.boolean().default(true),
+      /**
+       * Include file index header in output. Defaults to true — read as
+       * `index ?? true`, so screenshot-only bundles can reject an explicit value.
+       */
+      index: z.boolean().optional(),
       /** Text to prepend to bundle (e.g., review instructions for LLMs). */
       prompt: z.string().optional(),
+      /**
+       * Skipped by a full run, built when named: `srcpack <name>`. For bundles
+       * too slow, remote or situational to rebuild every time. A full run that
+       * empties `outDir` still removes their output there — preserving it
+       * would make emptying a growing list of exceptions (ADR 005).
+       */
+      onDemand: z.boolean().optional(),
     })
-    .refine((bundle) => bundle.include || bundle.linear, {
-      message: 'Bundle needs a source: "include" patterns, "linear", or both',
+    .superRefine((bundle, ctx) => {
+      if (bundle.include || bundle.linear) return;
+      if (!bundle.screenshot) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            'Bundle needs a source: "include" patterns, "linear", or "screenshot"',
+        });
+        return;
+      }
+      // These shape a text file that a screenshot-only bundle never writes, so
+      // setting one is a misunderstanding rather than a harmless no-op
+      for (const key of ["prompt", "index", "outfile"] as const) {
+        if (bundle[key] !== undefined) {
+          ctx.addIssue({
+            code: "custom",
+            path: [key],
+            message: `"${key}" applies to the text file, and a screenshot-only bundle writes none. Add "include" or "linear", or remove it`,
+          });
+        }
+      }
     }),
 ]);
 
@@ -164,10 +235,8 @@ const ConfigSchema = z
     bundles: z.record(BundleNameSchema, BundleConfigSchema),
   })
   .superRefine((config, ctx) => {
-    // `upload.exclude` is the only thing keeping a bundle off Google Drive, so a
-    // name that matches nothing uploads the bundle it was meant to hold back —
-    // the one failure mode where a typo is worse than a missing line. A stale
-    // entry left over from a deleted bundle is cheap to fix by comparison.
+    // Reject misspelled exclusions so a bundle intended to stay local cannot
+    // silently upload. Removed bundles must also be removed from this list.
     const uploads = config.upload
       ? Array.isArray(config.upload)
         ? config.upload
@@ -193,6 +262,7 @@ const ConfigSchema = z
 
 export type UploadConfig = z.infer<typeof UploadConfigSchema>;
 export type LinearSourceInput = z.input<typeof LinearSourceSchema>;
+export type ScreenshotSource = z.infer<typeof ScreenshotSourceSchema>;
 export type BundleConfig = z.infer<typeof BundleConfigSchema>;
 export type BundleConfigInput = z.input<typeof BundleConfigSchema>;
 export type Config = z.infer<typeof ConfigSchema>;

package/src/fs.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MIT
+
+import { realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+
+/**
+ * Compare paths using Unicode NFC followed by lowercase, on every platform.
+ * Normalizing first gives equivalent spellings the same input to lowercasing.
+ * This catches case and normalization collisions even for unwritten outputs
+ * and unresolved final entries, where realpath cannot canonicalize spelling.
+ * Applying one rule everywhere prevents a config from passing on Linux and
+ * overwriting a bundle on a case-insensitive filesystem (ADR 004).
+ *
+ * Comparison only: I/O retains the original spelling. Ownership and deletion
+ * use exact matches so folding cannot widen what srcpack removes.
+ */
+export function pathKey(path: string): string {
+  return path.normalize("NFC").toLowerCase();
+}
+
+/**
+ * Where a path physically is, with symlinks resolved. Destructive decisions are
+ * made on this rather than the lexical path: `.srcpack -> ../shared` is inside
+ * the project by name and somewhere else in fact, and it is the somewhere else
+ * whose contents `rm` would take.
+ *
+ * Resolves as much of the path as exists, however deep that is. Stopping at the
+ * immediate parent would call `.srcpack/nested/x.txt` and `alias/nested/x.txt`
+ * different files until `mkdir -p` runs, which is one step too late to still be
+ * a check: aliasing is a property of the ancestors, not of when they were made.
+ */
+export async function physicalPath(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    const parent = dirname(path);
+    // dirname("/") === "/": nothing above the filesystem root left to resolve
+    if (parent === path) return path;
+    return join(await physicalPath(parent), basename(path));
+  }
+}
+
+/**
+ * Where `rename` puts a directory entry: ancestors resolved, the entry itself
+ * left alone. Writing replaces the entry instead of following it, so a bundle
+ * whose output is a symlink is identified as the link rather than its target —
+ * writing to the link path and to its target produces two separate files.
+ */
+export async function entryPath(path: string): Promise<string> {
+  return join(await physicalPath(dirname(path)), basename(path));
+}
+
+export function isInside(path: string, dir: string): boolean {
+  const rel = relative(dir, path);
+  // Compare against ".." as a whole segment — "..cache/x" is a child, not an escape
+  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/**
+ * Write a file by replacing the directory entry rather than the file behind
+ * it. Writing in place follows a symlink sitting at the output path, so
+ * `.srcpack/web.txt -> ~/.ssh/config` would be written through; rename replaces
+ * the link itself. It also makes each file appear whole or not at all.
+ *
+ * The temp name carries the pid so two runs can't rename each other's file.
+ */
+export async function writeFileAtomic(
+  path: string,
+  data: string | Uint8Array,
+): Promise<void> {
+  const temp = `${path}.${process.pid}.tmp`;
+  try {
+    await writeFile(temp, data);
+    await rename(temp, path);
+  } finally {
+    // A failed write or rename would otherwise leave a partial file behind:
+    // stale inside outDir, and bundled by the next run beside a custom outfile.
+    await rm(temp, { force: true });
+  }
+}

package/src/plan.ts

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: MIT
+
+import { basename, dirname, join, relative, resolve } from "node:path";
+import type { BundleResult } from "./bundle.ts";
+import { ConfigError, type BundleConfig } from "./config.ts";
+import { entryPath, pathKey, physicalPath } from "./fs.ts";
+import {
+  isImageOf,
+  toScreenshotTarget,
+  type CapturedPage,
+  type ScreenshotTarget,
+} from "./screenshot.ts";
+
+// Check output destinations before resolving sources or launching a browser.
+// Retain each active plan through writing, reporting and upload.
+
+/** 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[];
+}
+
+function isOnDemand(config: BundleConfig): boolean {
+  return (
+    typeof config === "object" &&
+    !Array.isArray(config) &&
+    config.onDemand === true
+  );
+}
+
+/**
+ * Pick the bundles a run builds. Naming a bundle always builds it; a full run
+ * builds everything not marked `onDemand`.
+ */
+export function selectBundles(
+  bundles: Record<string, BundleConfig>,
+  requested: string[],
+): BundleSelection {
+  for (const name of requested) {
+    // hasOwn, not `in`: `srcpack toString` would otherwise find Object.prototype
+    if (!Object.hasOwn(bundles, name)) {
+      throw new ConfigError(`Unknown bundle: ${name}`);
+    }
+  }
+  if (requested.length) {
+    return { names: [...new Set(requested)], skipped: [] };
+  }
+
+  const names: string[] = [];
+  const skipped: string[] = [];
+  for (const [name, config] of Object.entries(bundles)) {
+    (isOnDemand(config) ? skipped : names).push(name);
+  }
+  return { names, skipped };
+}
+
+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[];
+}
+
+function planBundle(
+  name: string,
+  source: BundleConfig,
+  root: string,
+  outDir: string,
+): PlannedBundle {
+  const object =
+    typeof source === "object" && !Array.isArray(source) ? source : undefined;
+  const plan: PlannedBundle = { name, source };
+  // Every bundle writes text unless a screenshot is all it declares
+  if (!object || object.include || object.linear) {
+    const outfile = object?.outfile ?? join(outDir, `${name}.txt`);
+    plan.text = { outfile: resolve(root, outfile) };
+  }
+  // Keep image cleanup within outDir, independent of any text outfile.
+  if (object?.screenshot) {
+    plan.images = {
+      target: toScreenshotTarget(object.screenshot),
+      dir: resolve(root, outDir),
+    };
+  }
+  return plan;
+}
+
+/**
+ * A claim on a destination: a text file, or an image family — a directory
+ * plus a name prefix. Compared folded (`pathKey`) and physically.
+ *
+ * A text file's directory is its entry path's parent, as for any output. A
+ * family's directory resolves fully: it is an ancestor of every PNG, and
+ * `rename` replaces only the last component (ADR 004).
+ */
+interface Claim {
+  owner: string;
+  kind: "file" | "family";
+  dir: string;
+  /** Folded file name, or folded bundle name for a family. */
+  name: string;
+  /** Absolute path shown in a collision message. */
+  display: string;
+}
+
+function overlaps(a: Claim, b: Claim): boolean {
+  if (a.dir !== b.dir) return false;
+  if (a.kind === b.kind) return a.name === b.name;
+  const [file, family] = a.kind === "file" ? [a, b] : [b, a];
+  return isImageOf(family.name, file.name);
+}
+
+/** `entry` is the text output's entry path, resolved once by the caller. */
+async function claimsOf(
+  plan: PlannedBundle,
+  entry: string | undefined,
+): Promise<Claim[]> {
+  const claims: Claim[] = [];
+  if (plan.text && entry) {
+    claims.push({
+      owner: plan.name,
+      kind: "file",
+      dir: pathKey(dirname(entry)),
+      name: pathKey(basename(entry)),
+      display: plan.text.outfile,
+    });
+  }
+  if (plan.images) {
+    claims.push({
+      owner: plan.name,
+      kind: "family",
+      dir: pathKey(await physicalPath(plan.images.dir)),
+      name: pathKey(plan.name),
+      display: join(plan.images.dir, `${plan.name}-NN.png`),
+    });
+  }
+  return claims;
+}
+
+function collision(first: Claim, second: Claim, root: string): ConfigError {
+  // Name the later bundle's destination, unless only the earlier one is a file:
+  // a file is what the user can change
+  const { display } =
+    first.kind === "file" && second.kind === "family" ? first : second;
+  const where = relative(root, display) || display;
+  if (first.owner === second.owner) {
+    return new ConfigError(
+      `Bundle "${first.owner}" writes its text and its images to "${where}". Give it another outfile.`,
+    );
+  }
+  return new ConfigError(
+    `Bundles "${first.owner}" and "${second.owner}" both write to "${where}". ` +
+      (first.kind === "family" && second.kind === "family"
+        ? "Rename one of them."
+        : "Give one of them its own outfile."),
+  );
+}
+
+/**
+ * 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 async function planOutputs(
+  root: string,
+  outDir: string,
+  configured: Record<string, BundleConfig>,
+  active: [name: string, source: BundleConfig][],
+): Promise<OutputPlan> {
+  const ownOutputs = new Set<string>();
+  const claims: Claim[] = [];
+
+  const claim = async (plan: PlannedBundle, shadowsOwnName: boolean) => {
+    const entry = plan.text && (await entryPath(plan.text.outfile));
+    for (const next of await claimsOf(plan, entry)) {
+      const taken = claims.find(
+        (prior) =>
+          !(shadowsOwnName && prior.owner === next.owner) &&
+          overlaps(prior, next),
+      );
+      if (taken) throw collision(taken, next, root);
+      claims.push(next);
+    }
+    if (plan.text && entry) {
+      ownOutputs.add(plan.text.outfile);
+      ownOutputs.add(entry);
+    }
+  };
+
+  for (const [name, source] of Object.entries(configured)) {
+    await claim(planBundle(name, source, root, outDir), false);
+  }
+
+  const bundles: PlannedBundle[] = [];
+  for (const [name, source] of active) {
+    const plan = planBundle(name, source, root, outDir);
+    await claim(plan, true);
+    bundles.push(plan);
+  }
+
+  return { bundles, ownOutputs: [...ownOutputs] };
+}