srcpack 0.2.0 → 1.0.0

package/dist/config.d.ts

@@ -1,5 +1,50 @@
 import { z } from "zod";
 export declare function expandPath(p: string): string;
+/**
+ * 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" } },
+ * }
+ * ```
+ */
+declare const LinearSourceSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    team: z.ZodString;
+    project: z.ZodOptional<z.ZodString>;
+    includeClosed: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>]>;
+/**
+ * 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" } },
+ * }
+ * ```
+ */
+declare const ScreenshotSourceSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    url: z.ZodString;
+    viewport: z.ZodOptional<z.ZodEnum<{
+        desktop: "desktop";
+        mobile: "mobile";
+    }>>;
+    hide: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>]>;
 /**
  * Bundle configuration. Accepts a string pattern, array of patterns, or object.
  * Patterns prefixed with `!` are exclusions. Patterns prefixed with `+` force
@@ -9,17 +54,37 @@ export declare function expandPath(p: string): string;
  * `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" } },
+ * }
  * ```
  */
 declare const BundleConfigSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
-    include: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    include: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    linear: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        team: z.ZodString;
+        project: z.ZodOptional<z.ZodString>;
+        includeClosed: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+    screenshot: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        url: z.ZodString;
+        viewport: z.ZodOptional<z.ZodEnum<{
+            desktop: "desktop";
+            mobile: "mobile";
+        }>>;
+        hide: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>]>>;
     outfile: z.ZodOptional<z.ZodString>;
-    index: z.ZodDefault<z.ZodBoolean>;
+    index: z.ZodOptional<z.ZodBoolean>;
     prompt: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>]>;
+    onDemand: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>]>;
 /**
  * Upload destination configuration.
  *
@@ -40,7 +105,7 @@ declare const UploadConfigSchema: z.ZodObject<{
     clientId: z.ZodString;
     clientSecret: z.ZodString;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 /** Root configuration for srcpack. */
 declare const ConfigSchema: z.ZodObject<{
     root: z.ZodDefault<z.ZodString>;
@@ -52,21 +117,37 @@ declare const ConfigSchema: z.ZodObject<{
         clientId: z.ZodString;
         clientSecret: z.ZodString;
         exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+    }, z.core.$strict>, 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>>]>>;
+    }, z.core.$strict>>]>>;
     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>]>;
+        include: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        linear: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            team: z.ZodString;
+            project: z.ZodOptional<z.ZodString>;
+            includeClosed: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>]>>;
+        screenshot: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            url: z.ZodString;
+            viewport: z.ZodOptional<z.ZodEnum<{
+                desktop: "desktop";
+                mobile: "mobile";
+            }>>;
+            hide: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>]>>;
         outfile: z.ZodOptional<z.ZodString>;
-        index: z.ZodDefault<z.ZodBoolean>;
+        index: z.ZodOptional<z.ZodBoolean>;
         prompt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>>;
-}, z.core.$strip>;
+        onDemand: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
 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/dist/fs.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 declare function pathKey(path: string): string;
+/**
+ * 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 declare function physicalPath(path: string): Promise<string>;
+/**
+ * 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 declare function entryPath(path: string): Promise<string>;
+export declare function isInside(path: string, dir: string): boolean;
+/**
+ * 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 declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;