srcpack 0.2.0 → 1.0.0

package/src/config.ts

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: MIT
 
+import { cosmiconfig } from "cosmiconfig";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { cosmiconfig } from "cosmiconfig";
 import { z } from "zod";
 
 export function expandPath(p: string): string {
@@ -18,6 +18,104 @@ const PatternsSchema = z.union([
   z.array(z.string().min(1)).min(1),
 ]);
 
+/**
+ * A name typed by a human and handed to a remote API. Trimmed, because a key
+ * pasted with a stray space fails as "not found" or "not authorized", which
+ * reads like the wrong key rather than the wrong whitespace.
+ */
+const IdentifierSchema = z.string().trim().min(1);
+
+/**
+ * A bundle name, which is also a filename: the default output is
+ * `<outDir>/<name>.txt`. Unconstrained, `"../report"` writes outside `outDir`
+ * entirely, and a leading `-` names a bundle the CLI can never be asked for.
+ */
+const BundleNameSchema = z
+  .string()
+  .regex(
+    /^[A-Za-z0-9][A-Za-z0-9._-]*$/,
+    "Bundle name must start with a letter or digit and contain only letters, digits, dot, underscore or hyphen",
+  );
+
+// Every closed object below is strict. Zod strips unknown keys by default, and
+// a stripped key is a typo that changes behaviour without saying so: `liner`
+// drops a bundle's issues, `emptyOutdir` hands the decision back to the
+// automatic default, `exlude` uploads the bundle it was meant to hold back.
+// Config files are edited by hand and read by a machine — the failure has to be
+// loud. Adding a key is a minor version either way, so nothing is lost.
+
+/**
+ * Linear issues as a bundle source. Each issue becomes a virtual file at
+ * `linear/issues/<identifier>.md`, so it gets its own index entry and line
+ * range and can be filtered with ordinary `!` exclusions.
+ *
+ * Authentication reads `LINEAR_API_KEY` from the environment. It is
+ * deliberately not a config field: config files are committed, and the
+ * `package.json` config form cannot express `process.env`.
+ *
+ * `team` is required. A workspace-wide fetch is a footgun — it looks innocuous
+ * and can pull thousands of issues into a context window.
+ *
+ * @example
+ * ```ts
+ * bundles: {
+ *   backlog: { linear: "ENG" },
+ *   roadmap: { linear: { team: "ENG", project: "Roadmap" } },
+ * }
+ * ```
+ */
+const LinearSourceSchema = z.union([
+  /** Shorthand for `{ team: "<key>" }`. */
+  IdentifierSchema,
+  z.strictObject({
+    /** Team key — the `ENG` in issue identifier `ENG-123`. */
+    team: IdentifierSchema,
+    /** Project name. Must name exactly one project within the team. */
+    project: IdentifierSchema.optional(),
+    /** Include completed, canceled and duplicate issues. Defaults to false. */
+    includeClosed: z.boolean().default(false),
+  }),
+]);
+
+/**
+ * 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
@@ -27,24 +125,67 @@ const PatternsSchema = 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`), page
+ * screenshots (`screenshot`), or any combination.
+ *
  * @example
  * ```ts
- * bundles: { review: ["git:staged", "!bun.lock"] }
+ * bundles: {
+ *   review: ["git:staged", "!bun.lock"],
+ *   planning: { include: ["docs/**"], linear: { team: "ENG" } },
+ * }
  * ```
  */
 const BundleConfigSchema = z.union([
   z.string().min(1),
   z.array(z.string().min(1)).min(1),
-  z.object({
-    /** Glob patterns to include in the bundle. */
-    include: PatternsSchema,
-    /** Custom output file path. Defaults to `<outDir>/<bundleName>.txt`. */
-    outfile: z.string().optional(),
-    /** Include file index header in output. Defaults to true. */
-    index: z.boolean().default(true),
-    /** Text to prepend to bundle (e.g., review instructions for LLMs). */
-    prompt: z.string().optional(),
-  }),
+  z
+    .strictObject({
+      /** Glob patterns to include in the bundle. */
+      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 — 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(),
+    })
+    .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`,
+          });
+        }
+      }
+    }),
 ]);
 
 /**
@@ -61,39 +202,67 @@ const BundleConfigSchema = z.union([
  * }
  * ```
  */
-const UploadConfigSchema = z.object({
+const UploadConfigSchema = z.strictObject({
   /** Upload provider. Currently only "gdrive" is supported. */
   provider: z.literal("gdrive"),
   /** Google Drive folder ID to upload files to. If omitted, uploads to root. */
-  folderId: z.string().optional(),
+  folderId: IdentifierSchema.optional(),
   /** OAuth 2.0 client ID from Google Cloud Console. */
-  clientId: z.string().min(1),
+  clientId: IdentifierSchema,
   /** OAuth 2.0 client secret from Google Cloud Console. */
-  clientSecret: z.string().min(1),
+  clientSecret: IdentifierSchema,
   /** Bundle names to skip during upload. Supports exact names only. */
   exclude: z.array(z.string()).optional(),
 });
 
 /** Root configuration for srcpack. */
-const ConfigSchema = z.object({
-  /**
-   * Project root directory. Can be absolute or relative to CWD.
-   * @default process.cwd()
-   */
-  root: z.string().default(""),
-  /** Output directory for bundle files (relative to root). Defaults to ".srcpack". */
-  outDir: z.string().default(".srcpack"),
-  /** Empty outDir before bundling. Auto-enabled when outDir is inside project root. */
-  emptyOutDir: z.boolean().optional(),
-  /** Upload configuration for cloud storage. Single destination or array. */
-  upload: z
-    .union([UploadConfigSchema, z.array(UploadConfigSchema).min(1)])
-    .optional(),
-  /** Named bundles mapping bundle name to glob patterns or config object. */
-  bundles: z.record(z.string(), BundleConfigSchema),
-});
+const ConfigSchema = z
+  .strictObject({
+    /**
+     * Project root directory. Can be absolute or relative to CWD.
+     * @default process.cwd()
+     */
+    root: z.string().default(""),
+    /** Output directory for bundle files (relative to root). Defaults to ".srcpack". */
+    outDir: z.string().default(".srcpack"),
+    /** Empty outDir before writing. Automatic only for the default `.srcpack`. */
+    emptyOutDir: z.boolean().optional(),
+    /** Upload configuration for cloud storage. Single destination or array. */
+    upload: z
+      .union([UploadConfigSchema, z.array(UploadConfigSchema).min(1)])
+      .optional(),
+    /** Named bundles mapping bundle name to glob patterns or config object. */
+    bundles: z.record(BundleNameSchema, BundleConfigSchema),
+  })
+  .superRefine((config, ctx) => {
+    // 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
+        : [config.upload]
+      : [];
+    const names = new Set(Object.keys(config.bundles));
+
+    uploads.forEach((upload, i) => {
+      const path = Array.isArray(config.upload)
+        ? ["upload", i, "exclude"]
+        : ["upload", "exclude"];
+      for (const name of upload.exclude ?? []) {
+        if (!names.has(name)) {
+          ctx.addIssue({
+            code: "custom",
+            path,
+            message: `Unknown bundle "${name}"`,
+          });
+        }
+      }
+    });
+  });
 
 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>;
@@ -110,13 +279,57 @@ export class ConfigError extends Error {
   }
 }
 
+/** A zod issue, plus the nested issues a union or a bad record key carries. */
+interface Issue {
+  code: string;
+  message: string;
+  path: PropertyKey[];
+  /** One entry per union branch. */
+  errors?: Issue[][];
+  /** Why a record key was rejected. */
+  issues?: Issue[];
+}
+
+/**
+ * Reduce an issue to the leaves that actually explain it. Both wrappers say
+ * nothing on their own — "Invalid input", "Invalid key in record" — while the
+ * reason sits one level down.
+ */
+function flatten(issue: Issue, prefix: PropertyKey[] = []): Issue[] {
+  const path = [...prefix, ...issue.path];
+  const nested =
+    issue.code === "invalid_union"
+      ? issue.errors?.flat()
+      : issue.code === "invalid_key"
+        ? issue.issues
+        : undefined;
+  return nested?.length
+    ? nested.flatMap((child) => flatten(child, path))
+    : [{ ...issue, path }];
+}
+
+/**
+ * Describe the most specific reason a config failed.
+ *
+ * Bundle and upload configs are unions, and a union reports one failure per
+ * branch. Reporting the first would surface "expected string" from a branch
+ * that never applied, burying the branch that nearly matched — so prefer a
+ * leaf that says something other than "wrong type", deepest path first.
+ */
+function describe(issues: Issue[]): string {
+  const leaves = issues.flatMap((issue) => flatten(issue));
+  const specific = leaves.filter((leaf) => leaf.code !== "invalid_type");
+  const best = (specific.length ? specific : leaves).reduce((a, b) =>
+    b.path.length > a.path.length ? b : a,
+  );
+  const path = best.path.join(".");
+  return path ? `${path}: ${best.message}` : best.message;
+}
+
 export function parseConfig(value: unknown): Config {
   const result = ConfigSchema.safeParse(value);
   if (!result.success) {
-    const issue = result.error.issues[0]!;
-    const path = issue.path.join(".");
-    const message = path ? `${path}: ${issue.message}` : issue.message;
-    throw new ConfigError(message);
+    throw new ConfigError(describe(result.error.issues as unknown as Issue[]));
   }
 
   const config = result.data;

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 });
+  }
+}