srcpack 0.1.6 → 0.1.8

package/README.md

@@ -48,11 +48,14 @@ Or add to `package.json`:
 
 ### Options
 
-| Option    | Default    | Description                      |
-| --------- | ---------- | -------------------------------- |
-| `outDir`  | `.srcpack` | Output directory for bundles     |
-| `bundles` | —          | Named bundles with glob patterns |
-| `upload`  | —          | Upload destination(s)            |
+| Option        | Default    | Description                            |
+| ------------- | ---------- | -------------------------------------- |
+| `outDir`      | `.srcpack` | Output directory for bundles           |
+| `emptyOutDir` | `true`\*   | Empty output directory before bundling |
+| `bundles`     | —          | Named bundles with glob patterns       |
+| `upload`      | —          | Upload destination(s)                  |
+
+\*`emptyOutDir` defaults to `true` when `outDir` is inside project root. When `outDir` is outside root, a warning is emitted unless explicitly set.
 
 ### Bundle Config
 
@@ -90,6 +93,7 @@ export default defineConfig({
     folderId: "1ABC...", // Google Drive folder ID (from URL)
     clientId: "...",
     clientSecret: "...",
+    exclude: ["local"], // skip specific bundles
   },
 });
 ```
@@ -127,12 +131,14 @@ export function utils() {
 ## CLI
 
 ```bash
-npx srcpack              # Bundle all, upload if configured
-npx srcpack web api      # Bundle specific bundles only
-npx srcpack --dry-run    # Preview without writing files
-npx srcpack --no-upload  # Bundle only, skip upload
-npx srcpack init         # Interactive config setup
-npx srcpack login        # Authenticate with Google Drive
+npx srcpack                 # Bundle all, upload if configured
+npx srcpack web api         # Bundle specific bundles only
+npx srcpack --dry-run       # Preview without writing files
+npx srcpack --emptyOutDir   # Empty output directory before bundling
+npx srcpack --no-emptyOutDir # Keep existing files in output directory
+npx srcpack --no-upload     # Bundle only, skip upload
+npx srcpack init            # Interactive config setup
+npx srcpack login           # Authenticate with Google Drive
 ```
 
 ## API
@@ -159,6 +165,8 @@ const config = await loadConfig();
 - [Discord](https://discord.com/invite/aG83xEb6RX) — Questions, feedback, and discussion
 - [GitHub Issues](https://github.com/kriasoft/srcpack/issues) — Bug reports and feature requests
 
+New contributors and OSS maintainers are welcome — join us on Discord or open an issue / PR.
+
 ## Backers
 
 <a href="https://reactstarter.com/b/1"><img src="https://reactstarter.com/b/1.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/2"><img src="https://reactstarter.com/b/2.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/3"><img src="https://reactstarter.com/b/3.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/4"><img src="https://reactstarter.com/b/4.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/5"><img src="https://reactstarter.com/b/5.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/6"><img src="https://reactstarter.com/b/6.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/7"><img src="https://reactstarter.com/b/7.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/8"><img src="https://reactstarter.com/b/8.png" height="60" /></a>

package/dist/cli.js

@@ -204450,8 +204450,8 @@ var require_src8 = __commonJS((exports, module) => {
 });
 
 // src/cli.ts
-import { mkdir as mkdir3, writeFile as writeFile4 } from "node:fs/promises";
-import { dirname as dirname3, join as join6 } from "node:path";
+import { mkdir as mkdir3, readdir, rm, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname as dirname3, isAbsolute, join as join6, relative, resolve } from "node:path";
 
 // node_modules/ora/index.js
 import process8 from "node:process";
@@ -207577,22 +207577,52 @@ function normalizePatterns(config) {
 function isExcluded(filePath, matchers) {
   return matchers.some((match) => match(filePath));
 }
+function gitignoreToGlobPatterns(lines) {
+  const hasNegation = lines.some((line) => {
+    const trimmed = line.trim();
+    return trimmed.startsWith("!");
+  });
+  if (hasNegation)
+    return [];
+  const patterns = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+      continue;
+    if (trimmed.startsWith("/") || trimmed.includes("*") || trimmed.includes("?") || trimmed.includes("[") || trimmed.includes("/") || trimmed.includes("\\")) {
+      continue;
+    }
+    const name = trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+    if (name && /^[\w.-]+$/.test(name)) {
+      patterns.push(`**/${name}/**`);
+    }
+  }
+  return patterns;
+}
 async function loadGitignore(cwd) {
   const ig = import_ignore.default();
   const gitignorePath = join(cwd, ".gitignore");
+  let globPatterns = [];
   try {
     const content = await readFile(gitignorePath, "utf-8");
     ig.add(content);
+    globPatterns = gitignoreToGlobPatterns(content.split(`
+`));
   } catch {}
-  return ig;
+  return { ignore: ig, globPatterns };
 }
 async function resolvePatterns(config, cwd) {
   const { include, exclude, force } = normalizePatterns(config);
   const excludeMatchers = exclude.map((p) => import_picomatch.default(p));
-  const gitignore = await loadGitignore(cwd);
+  const { ignore: gitignore, globPatterns } = await loadGitignore(cwd);
   const files = new Set;
   if (include.length > 0) {
-    const matches = await import_fast_glob.glob(include, { cwd, onlyFiles: true, dot: true });
+    const matches = await import_fast_glob.glob(include, {
+      cwd,
+      onlyFiles: true,
+      dot: true,
+      ignore: globPatterns
+    });
     for (const match of matches) {
       if (!isExcluded(match, excludeMatchers) && !gitignore.ignores(match)) {
         const fullPath = join(cwd, match);
@@ -221253,10 +221283,12 @@ var UploadConfigSchema = exports_external.object({
   provider: exports_external.literal("gdrive"),
   folderId: exports_external.string().optional(),
   clientId: exports_external.string().min(1),
-  clientSecret: exports_external.string().min(1)
+  clientSecret: exports_external.string().min(1),
+  exclude: exports_external.array(exports_external.string()).optional()
 });
 var ConfigSchema = exports_external.object({
   outDir: exports_external.string().default(".srcpack"),
+  emptyOutDir: exports_external.boolean().optional(),
   upload: exports_external.union([UploadConfigSchema, exports_external.array(UploadConfigSchema).min(1)]).optional(),
   bundles: exports_external.record(exports_external.string(), BundleConfigSchema)
 });
@@ -223363,6 +223395,21 @@ function formatNumber(n) {
 function plural(n, singular, pluralForm) {
   return n === 1 ? singular : pluralForm ?? singular + "s";
 }
+function isOutDirInsideRoot(outDir, root) {
+  const absoluteOutDir = isAbsolute(outDir) ? outDir : resolve(root, outDir);
+  const rel = relative(root, absoluteOutDir);
+  return !rel.startsWith("..") && !isAbsolute(rel);
+}
+async function emptyDirectory(dir, skip = []) {
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  const skipSet = new Set(skip);
+  await Promise.all(entries.filter((entry) => !skipSet.has(entry)).map((entry) => rm(join6(dir, entry), { recursive: true, force: true })));
+}
 async function main() {
   const args = process.argv.slice(2);
   if (args.includes("--help") || args.includes("-h")) {
@@ -223378,9 +223425,11 @@ Usage:
   npx srcpack login        Authenticate with Google Drive
 
 Options:
-  --dry-run     Preview bundles without writing files
-  --no-upload   Skip uploading to cloud storage
-  -h, --help    Show this help message
+  --dry-run        Preview bundles without writing files
+  --emptyOutDir    Empty output directory before bundling
+  --no-emptyOutDir Keep existing files in output directory
+  --no-upload      Skip uploading to cloud storage
+  -h, --help       Show this help message
 `);
     return;
   }
@@ -223394,6 +223443,7 @@ Options:
   }
   const dryRun = args.includes("--dry-run");
   const noUpload = args.includes("--no-upload");
+  const emptyOutDirFlag = args.includes("--emptyOutDir") ? true : args.includes("--no-emptyOutDir") ? false : undefined;
   const subcommands = ["init", "login"];
   const requestedBundles = args.filter((arg) => !arg.startsWith("-") && !subcommands.includes(arg));
   const config2 = await loadConfig();
@@ -223413,6 +223463,15 @@ Options:
     return;
   }
   const cwd = process.cwd();
+  const outDirInsideRoot = isOutDirInsideRoot(config2.outDir, cwd);
+  const emptyOutDir = emptyOutDirFlag ?? config2.emptyOutDir ?? outDirInsideRoot;
+  if (!outDirInsideRoot && emptyOutDirFlag === undefined && config2.emptyOutDir === undefined) {
+    console.warn(`Warning: outDir "${config2.outDir}" is outside project root. ` + "Use --emptyOutDir to suppress this warning and empty the directory.");
+  }
+  if (emptyOutDir && !dryRun) {
+    const outDirPath = isAbsolute(config2.outDir) ? config2.outDir : resolve(cwd, config2.outDir);
+    await emptyDirectory(outDirPath, [".git"]);
+  }
   const outputs = [];
   const bundleSpinner = ora({
     text: `Bundling ${bundleNames[0]}...`,
@@ -223525,6 +223584,13 @@ function printUploadConfigHelp() {
 `);
 }
 async function handleGdriveUpload(uploadConfig, outputs, cwd) {
+  const excludeSet = new Set(uploadConfig.exclude ?? []);
+  const toUpload = outputs.filter((o2) => !excludeSet.has(o2.name));
+  if (toUpload.length === 0) {
+    console.log(`
+No bundles to upload (all excluded).`);
+    return;
+  }
   try {
     await ensureAuthenticated(uploadConfig);
     const uploadSpinner = ora({
@@ -223532,10 +223598,10 @@ async function handleGdriveUpload(uploadConfig, outputs, cwd) {
       color: "cyan"
     }).start();
     const results = [];
-    for (let i2 = 0;i2 < outputs.length; i2++) {
-      const output = outputs[i2];
+    for (let i2 = 0;i2 < toUpload.length; i2++) {
+      const output = toUpload[i2];
       const filePath = join6(cwd, output.outfile);
-      uploadSpinner.text = `Uploading ${output.name}... (${i2 + 1}/${outputs.length})`;
+      uploadSpinner.text = `Uploading ${output.name}... (${i2 + 1}/${toUpload.length})`;
       const result = await uploadFile(filePath, uploadConfig);
       results.push(result);
     }

package/dist/config.d.ts

@@ -1,28 +1,52 @@
 import { z } from "zod";
 export declare function expandPath(p: string): string;
+/**
+ * Bundle configuration. Accepts a string pattern, array of patterns, or object.
+ * Patterns prefixed with `!` are exclusions. Patterns prefixed with `+` force
+ * inclusion (bypass .gitignore).
+ */
 declare const BundleConfigSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
     include: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
     outfile: z.ZodOptional<z.ZodString>;
     index: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>]>;
+/**
+ * Upload destination configuration.
+ *
+ * @example
+ * ```ts
+ * upload: {
+ *   provider: "gdrive",
+ *   clientId: process.env.GDRIVE_CLIENT_ID,
+ *   clientSecret: process.env.GDRIVE_CLIENT_SECRET,
+ *   folderId: "1abc...",
+ *   exclude: ["local", "debug"],
+ * }
+ * ```
+ */
 declare const UploadConfigSchema: z.ZodObject<{
     provider: z.ZodLiteral<"gdrive">;
     folderId: z.ZodOptional<z.ZodString>;
     clientId: z.ZodString;
     clientSecret: z.ZodString;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/** Root configuration for srcpack. */
 declare const ConfigSchema: z.ZodObject<{
     outDir: z.ZodDefault<z.ZodString>;
+    emptyOutDir: z.ZodOptional<z.ZodBoolean>;
     upload: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         provider: z.ZodLiteral<"gdrive">;
         folderId: z.ZodOptional<z.ZodString>;
         clientId: z.ZodString;
         clientSecret: z.ZodString;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>, z.ZodArray<z.ZodObject<{
         provider: z.ZodLiteral<"gdrive">;
         folderId: z.ZodOptional<z.ZodString>;
         clientId: z.ZodString;
         clientSecret: z.ZodString;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>]>>;
     bundles: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
         include: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;

package/dist/index.js

@@ -187020,10 +187020,12 @@ var UploadConfigSchema = exports_external.object({
   provider: exports_external.literal("gdrive"),
   folderId: exports_external.string().optional(),
   clientId: exports_external.string().min(1),
-  clientSecret: exports_external.string().min(1)
+  clientSecret: exports_external.string().min(1),
+  exclude: exports_external.array(exports_external.string()).optional()
 });
 var ConfigSchema = exports_external.object({
   outDir: exports_external.string().default(".srcpack"),
+  emptyOutDir: exports_external.boolean().optional(),
   upload: exports_external.union([UploadConfigSchema, exports_external.array(UploadConfigSchema).min(1)]).optional(),
   bundles: exports_external.record(exports_external.string(), BundleConfigSchema)
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srcpack",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Zero-config CLI for bundling code into LLM-optimized context files",
   "keywords": [
     "llm",

package/src/bundle.ts

@@ -86,20 +86,79 @@ function isExcluded(filePath: string, matchers: Matcher[]): boolean {
 }
 
 /**
- * Load and parse .gitignore file from a directory
+ * Convert gitignore patterns to glob ignore patterns for fast-glob.
+ * This prevents traversing into ignored directories (performance optimization).
+ *
+ * Conservative approach: only convert simple, unambiguous directory patterns.
+ * Complex patterns (negations, root-anchored, globs) are left to the ignore filter.
  */
-async function loadGitignore(cwd: string): Promise<Ignore> {
+function gitignoreToGlobPatterns(lines: string[]): string[] {
+  // If any negation patterns exist, skip optimization entirely
+  // (negations could re-include files in otherwise-ignored directories)
+  const hasNegation = lines.some((line) => {
+    const trimmed = line.trim();
+    // Any line starting with ! is a negation (including !#file which negates "#file")
+    return trimmed.startsWith("!");
+  });
+  if (hasNegation) return [];
+
+  const patterns: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Skip empty lines and comments
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    // Skip patterns with special gitignore features we can't safely convert:
+    // - Root-anchored (starts with /)
+    // - Contains globs (*, ?, [)
+    // - Contains path separators (complex paths)
+    // - Escaped characters
+    if (
+      trimmed.startsWith("/") ||
+      trimmed.includes("*") ||
+      trimmed.includes("?") ||
+      trimmed.includes("[") ||
+      trimmed.includes("/") ||
+      trimmed.includes("\\")
+    ) {
+      continue;
+    }
+
+    // Only convert simple directory names (e.g., "node_modules", "dist")
+    // These are safe to prune at any depth
+    const name = trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+    if (name && /^[\w.-]+$/.test(name)) {
+      patterns.push(`**/${name}/**`);
+    }
+  }
+
+  return patterns;
+}
+
+interface GitignoreResult {
+  ignore: Ignore;
+  globPatterns: string[];
+}
+
+/**
+ * Load and parse .gitignore file from a directory.
+ * Returns both an Ignore instance for filtering and glob patterns for fast-glob.
+ */
+async function loadGitignore(cwd: string): Promise<GitignoreResult> {
   const ig = ignore();
   const gitignorePath = join(cwd, ".gitignore");
+  let globPatterns: string[] = [];
 
   try {
     const content = await readFile(gitignorePath, "utf-8");
     ig.add(content);
+    globPatterns = gitignoreToGlobPatterns(content.split("\n"));
   } catch {
     // No .gitignore file, return empty ignore instance
   }
 
-  return ig;
+  return { ignore: ig, globPatterns };
 }
 
 /**
@@ -114,12 +173,18 @@ export async function resolvePatterns(
 ): Promise<string[]> {
   const { include, exclude, force } = normalizePatterns(config);
   const excludeMatchers = exclude.map((p) => picomatch(p));
-  const gitignore = await loadGitignore(cwd);
+  const { ignore: gitignore, globPatterns } = await loadGitignore(cwd);
   const files = new Set<string>();
 
   // Regular includes: respect .gitignore
+  // Pass gitignore patterns to fast-glob to skip ignored directories during traversal
   if (include.length > 0) {
-    const matches = await glob(include, { cwd, onlyFiles: true, dot: true });
+    const matches = await glob(include, {
+      cwd,
+      onlyFiles: true,
+      dot: true,
+      ignore: globPatterns,
+    });
     for (const match of matches) {
       if (!isExcluded(match, excludeMatchers) && !gitignore.ignores(match)) {
         const fullPath = join(cwd, match);
@@ -130,7 +195,7 @@ export async function resolvePatterns(
     }
   }
 
-  // Force includes: bypass .gitignore
+  // Force includes: bypass .gitignore (no ignore patterns passed to glob)
   if (force.length > 0) {
     const matches = await glob(force, { cwd, onlyFiles: true, dot: true });
     for (const match of matches) {

package/src/cli.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
 
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import ora from "ora";
 import { bundleOne, type BundleResult } from "./bundle.ts";
 import {
@@ -38,6 +38,31 @@ function plural(n: number, singular: string, pluralForm?: string): string {
   return n === 1 ? singular : (pluralForm ?? singular + "s");
 }
 
+function isOutDirInsideRoot(outDir: string, root: string): boolean {
+  const absoluteOutDir = isAbsolute(outDir) ? outDir : resolve(root, outDir);
+  const rel = relative(root, absoluteOutDir);
+  return !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Empty a directory while preserving specified entries (e.g., `.git`).
+ * Uses `force: true` to handle read-only or in-use files.
+ */
+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
+  }
+  const skipSet = new Set(skip);
+  await Promise.all(
+    entries
+      .filter((entry) => !skipSet.has(entry))
+      .map((entry) => rm(join(dir, entry), { recursive: true, force: true })),
+  );
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -54,9 +79,11 @@ Usage:
   npx srcpack login        Authenticate with Google Drive
 
 Options:
-  --dry-run     Preview bundles without writing files
-  --no-upload   Skip uploading to cloud storage
-  -h, --help    Show this help message
+  --dry-run        Preview bundles without writing files
+  --emptyOutDir    Empty output directory before bundling
+  --no-emptyOutDir Keep existing files in output directory
+  --no-upload      Skip uploading to cloud storage
+  -h, --help       Show this help message
 `);
     return;
   }
@@ -73,6 +100,12 @@ Options:
 
   const dryRun = args.includes("--dry-run");
   const noUpload = args.includes("--no-upload");
+  // CLI flags: --emptyOutDir forces true, --no-emptyOutDir forces false
+  const emptyOutDirFlag = args.includes("--emptyOutDir")
+    ? true
+    : args.includes("--no-emptyOutDir")
+      ? false
+      : undefined;
   const subcommands = ["init", "login"];
   const requestedBundles = args.filter(
     (arg) => !arg.startsWith("-") && !subcommands.includes(arg),
@@ -106,6 +139,31 @@ Options:
   }
 
   const cwd = process.cwd();
+
+  // Resolve emptyOutDir: CLI flag > config > auto (true if inside root)
+  const outDirInsideRoot = isOutDirInsideRoot(config.outDir, cwd);
+  const emptyOutDir = emptyOutDirFlag ?? config.emptyOutDir ?? outDirInsideRoot;
+
+  // Warn if outDir is outside root and emptyOutDir is not explicitly set
+  if (
+    !outDirInsideRoot &&
+    emptyOutDirFlag === undefined &&
+    config.emptyOutDir === undefined
+  ) {
+    console.warn(
+      `Warning: outDir "${config.outDir}" is outside project root. ` +
+        "Use --emptyOutDir to suppress this warning and empty the directory.",
+    );
+  }
+
+  // Empty outDir before bundling (unless dry-run)
+  if (emptyOutDir && !dryRun) {
+    const outDirPath = isAbsolute(config.outDir)
+      ? config.outDir
+      : resolve(cwd, config.outDir);
+    await emptyDirectory(outDirPath, [".git"]);
+  }
+
   const outputs: BundleOutput[] = [];
 
   // Process all bundles with progress
@@ -279,6 +337,15 @@ async function handleGdriveUpload(
   outputs: BundleOutput[],
   cwd: string,
 ): Promise<void> {
+  // Filter out excluded bundles
+  const excludeSet = new Set(uploadConfig.exclude ?? []);
+  const toUpload = outputs.filter((o) => !excludeSet.has(o.name));
+
+  if (toUpload.length === 0) {
+    console.log("\nNo bundles to upload (all excluded).");
+    return;
+  }
+
   try {
     await ensureAuthenticated(uploadConfig);
 
@@ -289,10 +356,10 @@ async function handleGdriveUpload(
 
     const results: UploadResult[] = [];
 
-    for (let i = 0; i < outputs.length; i++) {
-      const output = outputs[i]!;
+    for (let i = 0; i < toUpload.length; i++) {
+      const output = toUpload[i]!;
       const filePath = join(cwd, output.outfile);
-      uploadSpinner.text = `Uploading ${output.name}... (${i + 1}/${outputs.length})`;
+      uploadSpinner.text = `Uploading ${output.name}... (${i + 1}/${toUpload.length})`;
       const result = await uploadFile(filePath, uploadConfig);
       results.push(result);
     }

package/src/config.ts

@@ -12,33 +12,68 @@ export function expandPath(p: string): string {
   return p;
 }
 
+/** Glob patterns for file matching. Single pattern or array of patterns. */
 const PatternsSchema = z.union([
   z.string().min(1),
   z.array(z.string().min(1)).min(1),
 ]);
 
+/**
+ * Bundle configuration. Accepts a string pattern, array of patterns, or object.
+ * Patterns prefixed with `!` are exclusions. Patterns prefixed with `+` force
+ * inclusion (bypass .gitignore).
+ */
 const BundleConfigSchema = z.union([
-  z.string().min(1), // "src/**/*"
-  z.array(z.string().min(1)).min(1), // ["src/**/*", "!src/specs"]
+  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(),
-    index: z.boolean().default(true), // Include index header in output
+    /** Include file index header in output. Defaults to true. */
+    index: z.boolean().default(true),
   }),
 ]);
 
+/**
+ * Upload destination configuration.
+ *
+ * @example
+ * ```ts
+ * upload: {
+ *   provider: "gdrive",
+ *   clientId: process.env.GDRIVE_CLIENT_ID,
+ *   clientSecret: process.env.GDRIVE_CLIENT_SECRET,
+ *   folderId: "1abc...",
+ *   exclude: ["local", "debug"],
+ * }
+ * ```
+ */
 const UploadConfigSchema = z.object({
+  /** 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(),
+  /** OAuth 2.0 client ID from Google Cloud Console. */
   clientId: z.string().min(1),
+  /** OAuth 2.0 client secret from Google Cloud Console. */
   clientSecret: z.string().min(1),
+  /** Bundle names to skip during upload. Supports exact names only. */
+  exclude: z.array(z.string()).optional(),
 });
 
+/** Root configuration for srcpack. */
 const ConfigSchema = z.object({
+  /** Output directory for bundle files. 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),
 });