srcpack 0.2.0 → 0.3.0

package/src/cli.ts

@@ -1,10 +1,26 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
 
-import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 import ora from "ora";
-import { bundleOne, type BundleResult } from "./bundle.ts";
+import { bundleOne, pathKey, type BundleResult } from "./bundle.ts";
 import {
   ConfigError,
   loadConfig,
@@ -12,7 +28,6 @@ import {
   type BundleConfig,
   type UploadConfig,
 } from "./config.ts";
-import { GitError } from "./git.ts";
 import {
   ensureAuthenticated,
   login,
@@ -20,7 +35,9 @@ import {
   uploadFile,
   type UploadResult,
 } from "./gdrive.ts";
+import { GitError } from "./git.ts";
 import { runInit } from "./init.ts";
+import { LinearError } from "./linear.ts";
 
 interface BundleOutput {
   name: string;
@@ -40,12 +57,67 @@ function plural(n: number, singular: string, pluralForm?: string): string {
   return n === 1 ? singular : (pluralForm ?? singular + "s");
 }
 
+/** The directory srcpack owns by convention, and the only one it clears unasked. */
+const DEFAULT_OUT_DIR = ".srcpack";
+
+/**
+ * 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.
+ */
+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 —
+ * two bundles writing over one link's target are still two separate files.
+ */
+async function entryPath(path: string): Promise<string> {
+  return join(await physicalPath(dirname(path)), basename(path));
+}
+
 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 bundle 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.
+ */
+async function writeBundle(path: string, content: string): Promise<void> {
+  const temp = `${path}.${process.pid}.tmp`;
+  try {
+    await writeFile(temp, content);
+    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 });
+  }
+}
+
 /**
  * Empty a directory while preserving specified entries (e.g., `.git`).
  * Uses `force: true` to handle read-only or in-use files.
@@ -54,8 +126,14 @@ async function emptyDirectory(dir: string, skip: string[] = []): Promise<void> {
   let entries: string[];
   try {
     entries = await readdir(dir);
-  } catch {
-    return; // Directory doesn't exist, nothing to empty
+  } catch (error) {
+    // Only a missing directory is "nothing to empty". Anything else — a
+    // permission error, a file where a directory belongs — would otherwise be
+    // reported as a clean run that then writes into a directory it never read.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw new ConfigError(
+      `Cannot empty outDir "${dir}": ${(error as Error).message}`,
+    );
   }
   const skipSet = new Set(skip);
   await Promise.all(
@@ -76,6 +154,39 @@ interface AdHocBundle {
 
 const AD_HOC_FLAGS = ["--staged", "--dirty", "--since"] as const;
 
+/**
+ * Every option the CLI accepts. Anything else is a typo, and 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.
+ */
+const KNOWN_FLAGS = new Set([
+  ...AD_HOC_FLAGS,
+  "--dry-run",
+  "--emptyOutDir",
+  "--no-emptyOutDir",
+  "--no-upload",
+  "--help",
+  "-h",
+  "--version",
+  "-v",
+]);
+
+function assertKnownFlags(args: string[]): void {
+  const unknown = args.find(
+    (arg) => arg.startsWith("-") && !KNOWN_FLAGS.has(arg),
+  );
+  if (unknown) {
+    console.error(`Unknown option: ${unknown}`);
+    console.error("Run `srcpack --help` to see the available options.");
+    process.exit(1);
+  }
+  if (args.includes("--emptyOutDir") && args.includes("--no-emptyOutDir")) {
+    console.error("Cannot combine --emptyOutDir with --no-emptyOutDir.");
+    process.exit(1);
+  }
+}
+
 function parseAdHocBundle(args: string[]): AdHocBundle | null {
   const flags = AD_HOC_FLAGS.filter((flag) => args.includes(flag));
 
@@ -147,7 +258,7 @@ Options:
   --dirty          Bundle staged, unstaged, and untracked changes
   --since <rev>    Bundle changes since <rev> (e.g. --since main)
   --dry-run        Preview bundles without writing files
-  --emptyOutDir    Empty output directory before bundling
+  --emptyOutDir    Empty output directory before writing
   --no-emptyOutDir Keep existing files in output directory
   --no-upload      Skip uploading to cloud storage
   -h, --help       Show this help message
@@ -158,15 +269,18 @@ Options:
 
   // Only in first position: elsewhere the word is a bundle name or a revision,
   // and `--since init` must diff against the `init` branch, not run the wizard.
-  if (args[0] === "init") {
-    await runInit();
+  if (args[0] === "init" || args[0] === "login") {
+    // Neither takes arguments, so anything after is a misunderstanding worth
+    // saying out loud rather than a flag that silently does nothing.
+    if (args.length > 1) {
+      console.error(`srcpack ${args[0]} takes no arguments.`);
+      process.exit(1);
+    }
+    await (args[0] === "init" ? runInit() : runLogin());
     return;
   }
 
-  if (args[0] === "login") {
-    await runLogin();
-    return;
-  }
+  assertKnownFlags(args);
 
   const dryRun = args.includes("--dry-run");
   const noUpload = args.includes("--no-upload");
@@ -210,7 +324,8 @@ Options:
 
   // Validate requested bundle names exist
   for (const name of bundleNames) {
-    if (!(name in bundles)) {
+    // hasOwn, not `in`: `srcpack toString` would otherwise find Object.prototype
+    if (!Object.hasOwn(bundles, name)) {
       console.error(`Unknown bundle: ${name}`);
       process.exit(1);
     }
@@ -223,30 +338,43 @@ Options:
 
   const root = config.root;
 
-  // Resolve emptyOutDir: CLI flag > config > auto (true if inside root).
-  // Ad-hoc runs never empty by default — they shouldn't delete configured bundles.
+  // Resolve emptyOutDir: CLI flag > config > auto.
+  //
+  // Auto means only the conventional `.srcpack`: recursive deletion needs a
+  // directory srcpack demonstrably owns, and `outDir: "src"` reads as an
+  // ordinary setting while turning a bundling run into a source-tree wipe.
+  // Every other directory belongs to the user until they say otherwise.
+  //
+  // The comparison is physical, not lexical: `.srcpack -> ../shared` looks
+  // inside the project and deletes somewhere else. Ad-hoc runs never empty by
+  // default either — they shouldn't delete configured bundles.
+  // Lexical is what gets written to and excluded from bundles; physical is what
+  // decides ownership. Conflating them is what let a symlink redirect a delete.
+  const rootPath = await physicalPath(root);
   const outDirPath = resolve(root, config.outDir);
-  const outDirInsideRoot = isInside(outDirPath, root);
-  const emptyOutDir =
-    emptyOutDirFlag ??
-    (adHoc ? false : (config.emptyOutDir ?? outDirInsideRoot));
+  const outDirPhysical = await physicalPath(outDirPath);
+  const defaultOutDir = join(rootPath, DEFAULT_OUT_DIR);
 
-  // Warn if outDir is outside root and emptyOutDir is not explicitly set
+  // The conventional name is a claim about a place. A `.srcpack` that resolves
+  // somewhere else keeps the name while writing into a directory srcpack was
+  // never given — and would overwrite whatever shares a filename there.
   if (
-    !adHoc &&
-    !outDirInsideRoot &&
-    emptyOutDirFlag === undefined &&
-    config.emptyOutDir === undefined
+    resolve(root, DEFAULT_OUT_DIR) === outDirPath &&
+    outDirPhysical !== defaultOutDir
   ) {
-    console.warn(
-      `Warning: outDir "${config.outDir}" is outside project root. ` +
-        "Use --emptyOutDir to suppress this warning and empty the directory.",
+    throw new ConfigError(
+      `Refusing to use "${DEFAULT_OUT_DIR}": it resolves to "${outDirPhysical}", not "${defaultOutDir}". ` +
+        "Set outDir to that path explicitly if that is where bundles belong.",
     );
   }
 
+  const ownsOutDir = outDirPhysical === defaultOutDir;
+  const emptyOutDir =
+    emptyOutDirFlag ?? (adHoc ? false : (config.emptyOutDir ?? ownsOutDir));
+
   // `outDir: "."` resolves to the project root, where emptying deletes the
   // whole project — sources, config and all. Refuse rather than warn.
-  const outDirHoldsRoot = isInside(root, outDirPath);
+  const outDirHoldsRoot = isInside(rootPath, outDirPhysical);
   if (emptyOutDir && outDirHoldsRoot) {
     throw new ConfigError(
       `Refusing to empty outDir "${config.outDir}": it contains the project root. ` +
@@ -254,20 +382,43 @@ Options:
     );
   }
 
-  // Empty outDir before bundling (unless dry-run). Only for a full run: a named
-  // subset can't tell what is stale, so `srcpack web` must not delete api.txt.
-  if (emptyOutDir && !dryRun && requestedBundles.length === 0) {
-    await emptyDirectory(outDirPath, [".git"]);
-  }
-
   // srcpack never bundles what srcpack writes. Every configured outfile is
   // named explicitly; outDir covers stale bundles from renamed config entries
   // too, but not when it holds the root — that would exclude the whole project.
-  const ownOutputs = Object.entries(config.bundles).map(
-    ([name, bundleConfig]) =>
-      resolve(root, getOutfile(bundleConfig, name, config.outDir)),
-  );
-  if (!outDirHoldsRoot) ownOutputs.push(outDirPath);
+  //
+  // Both spellings of every output are recorded. 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.
+  const ownOutputs = new Set<string>();
+  const writers = new Map<string, string>();
+  for (const [name, bundleConfig] of Object.entries(config.bundles)) {
+    const outfile = resolve(
+      root,
+      getOutfile(bundleConfig, name, config.outDir),
+    );
+    // Two bundles sharing one file is silent loss: the second write replaces the
+    // first, and the upload step then sends the survivor twice under two names.
+    // Keyed by destination entry — `.srcpack/a.txt` and `alias/a.txt` are two
+    // spellings of one file as soon as `alias` links to `.srcpack`, and so are
+    // `Web.txt` and `web.txt` wherever the filesystem folds case.
+    const entry = await entryPath(outfile);
+    const key = pathKey(entry);
+    const first = writers.get(key);
+    if (first) {
+      throw new ConfigError(
+        `Bundles "${first}" and "${name}" both write to "${relative(root, outfile) || outfile}". ` +
+          "Give one of them its own outfile.",
+      );
+    }
+    writers.set(key, name);
+    ownOutputs.add(outfile);
+    ownOutputs.add(entry);
+  }
+  if (!outDirHoldsRoot) {
+    ownOutputs.add(outDirPath);
+    ownOutputs.add(outDirPhysical);
+  }
+  const outputPaths = [...ownOutputs];
 
   const outputs: BundleOutput[] = [];
 
@@ -282,7 +433,21 @@ Options:
       const name = bundleNames[i]!;
       bundleSpinner.text = `Bundling ${name}... (${i + 1}/${bundleNames.length})`;
       const bundleConfig = bundles[name]!;
-      const result = await bundleOne(bundleConfig, root, ownOutputs);
+      let result: BundleResult;
+      try {
+        result = await bundleOne(bundleConfig, root, outputPaths);
+      } catch (error) {
+        // A config can declare many bundles; the underlying message says what
+        // broke but not which bundle asked for it.
+        if (
+          error instanceof ConfigError ||
+          error instanceof GitError ||
+          error instanceof LinearError
+        ) {
+          error.message = `Bundle "${name}": ${error.message}`;
+        }
+        throw error;
+      }
       const outfile = getOutfile(bundleConfig, name, config.outDir);
       outputs.push({ name, outfile, result });
     }
@@ -290,6 +455,17 @@ Options:
     bundleSpinner.stop();
   }
 
+  // Empty outDir only once every bundle has resolved, and only for a full run:
+  // a named subset can't tell what is stale, so `srcpack web` must not delete
+  // api.txt. Emptying earlier would destroy a good previous run whenever a
+  // later bundle fails — routine once a source is remote, since an expired
+  // token or a rate limit aborts the run after outDir is already gone.
+  // Resolution doesn't need the files removed first: `ownOutputs` already keeps
+  // srcpack's own output from being bundled.
+  if (emptyOutDir && !dryRun && requestedBundles.length === 0) {
+    await emptyDirectory(outDirPath, [".git"]);
+  }
+
   // Calculate column widths for aligned output
   const maxNameLen = Math.max(...outputs.map((o) => o.name.length));
   const maxFilesLen = Math.max(
@@ -328,7 +504,7 @@ Options:
       );
     } else {
       await mkdir(dirname(outPath), { recursive: true });
-      await writeFile(outPath, result.content);
+      await writeBundle(outPath, result.content);
       const displayPath = relative(process.cwd(), outPath);
       console.log(
         `  ${nameCol}  ${filesCol} ${plural(fileCount, "file")}  ${linesCol} ${plural(lineCount, "line")}  → ${displayPath}`,
@@ -378,16 +554,6 @@ function isGdriveConfigured(config: UploadConfig): boolean {
   );
 }
 
-function getGdriveConfig(config: {
-  upload?: UploadConfig | UploadConfig[];
-}): UploadConfig | null {
-  if (!config.upload) return null;
-  const uploads = Array.isArray(config.upload)
-    ? config.upload
-    : [config.upload];
-  return uploads.find(isGdriveConfigured) ?? null;
-}
-
 async function runLogin(): Promise<void> {
   let config;
   try {
@@ -531,9 +697,13 @@ function getOutfile(
 }
 
 main().catch((err) => {
-  // Config and git failures are user-facing; a stack trace only adds noise
+  // Config, git and Linear failures are user-facing; a stack trace adds noise
   console.error(
-    err instanceof ConfigError || err instanceof GitError ? err.message : err,
+    err instanceof ConfigError ||
+      err instanceof GitError ||
+      err instanceof LinearError
+      ? err.message
+      : err,
   );
   process.exit(1);
 });

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,65 @@ 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),
+  }),
+]);
+
 /**
  * Bundle configuration. Accepts a string pattern, array of patterns, or object.
  * Patterns prefixed with `!` are exclusions. Patterns prefixed with `+` force
@@ -27,24 +86,35 @@ 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`), or both.
+ *
  * @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(),
+      /** 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),
+      /** Text to prepend to bundle (e.g., review instructions for LLMs). */
+      prompt: z.string().optional(),
+    })
+    .refine((bundle) => bundle.include || bundle.linear, {
+      message: 'Bundle needs a source: "include" patterns, "linear", or both',
+    }),
 ]);
 
 /**
@@ -61,39 +131,68 @@ 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) => {
+    // `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.
+    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 BundleConfig = z.infer<typeof BundleConfigSchema>;
 export type BundleConfigInput = z.input<typeof BundleConfigSchema>;
 export type Config = z.infer<typeof ConfigSchema>;
@@ -110,13 +209,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;