mintree 0.5.11 → 0.5.13

package/README.md

@@ -161,6 +161,29 @@ Three top-level keys in `.mintree/metadata.json` tune how mintree launches Claud
 
   When omitted, mintree uses a built-in default that asks Claude to orchestrate the selected tickets with minimal intervention — parallelising via subagents unless dependencies force sequential work, creating a worktree per ticket with mintree, using the repo's skills, and moving each ticket to *in progress* on start and closing it when done.
 
+### Linking gitignored files into worktrees (optional)
+
+Git worktrees don't share **untracked** files: a new worktree is a fresh working directory, so gitignored config like `.env` lives only in your main checkout and is **absent** in every worktree mintree creates. That breaks per-worktree tooling that needs it — e.g. running an E2E suite that reads `.env` for staging credentials.
+
+The `linkFiles` top-level key (valid on GitHub and Linear repos) lists repo-root-relative paths that mintree **symlinks** into each new worktree, right after creating it:
+
+```json
+{
+  "version": 1,
+  "provider": "linear",
+  "issues": {},
+  "linkFiles": [".env"],
+  "linear": { "workspaceSlug": "my-team", "teams": [{ "key": "FE" }] }
+}
+```
+
+- **Symlink, not copy** — one source of truth. Rotate a credential in the main `.env` and every worktree sees it; no re-copying. `worktree remove` deletes the link, never the original file.
+- **Best-effort, never fatal** — an entry that doesn't exist in the repo root is skipped, and so is one whose target is already present in the worktree (e.g. a tracked file). Both show up as `skip` steps in the create log.
+- **Runs before `.mintree/init.sh`** — so the post-create hook (if any) can rely on the linked files being there.
+- **Sandboxed paths** — entries must be repo-root-relative; absolute paths and `..` escapes are dropped on read, so a stray `metadata.json` can't make mintree link something outside the worktree.
+
+This applies to `worktree create` (CLI), the dashboard `w` overlay, and the detached-worktree flow alike. For more involved per-worktree setup (installing deps, copying templated files), use `.mintree/init.sh` instead — see [What gets stored where](#what-gets-stored-where).
+
 ---
 
 ## Daily flow
@@ -188,7 +211,7 @@ It has three tabs, switched with `←` / `→`:
 | `a`      | Orchestrate tab: select / deselect all visible tickets               |
 | `w`      | Always open the create overlay (type + kebab description)             |
 | `d`      | Delete the selected worktree (confirmation overlay)                   |
-| `r`      | Manual refresh (auto-refreshes silently every 5 min)                  |
+| `r`      | Manual refresh — bypasses the Linear snapshot cache, so a just-assigned ticket shows up immediately (auto-refreshes silently every 5 min) |
 | `o`      | Open the issue in your browser                                        |
 | `q`/`Esc`| Quit (or cancel an open overlay)                                      |
 
@@ -276,7 +299,7 @@ The worktree directory is still the **bare, upper-case issue id** (`VAL-68`) reg
     │   └── FE-123/               # Linear form: <TEAM-digits>
     ├── session-states/           # gitignored
     │   └── 100.json              # live state written by Claude hooks (active/waiting/idle/exited)
-    └── init.sh                   # opt-in. Runs in the new worktree post-create (copy .env, install deps, …)
+    └── init.sh                   # opt-in. Runs in the new worktree post-create (install deps, scaffold, …)
 ```
 
 The worktree directory is named after the bare issue id (`100`, `FE-123`, `VAL-68`); the branch keeps its full name — `<type>/<issue>-<desc>` for the convention, or Linear's own `<user>/<team>-<n>-<desc>` on Linear repos.

package/dist/commands/dashboard.js

@@ -669,7 +669,7 @@ export default function Dashboard() {
     // Live value for the mouse handler (mounted once) to read without
     // re-binding on every resize.
     const listWidthRef = useRef(0);
-    const refresh = async () => {
+    const refresh = async (opts) => {
         const root = findMainRepoRoot();
         if (!root) {
             setState({
@@ -687,7 +687,7 @@ export default function Dashboard() {
             });
             return;
         }
-        const issues = await loadDashboard(root);
+        const issues = await loadDashboard(root, opts);
         if (!issues) {
             const provider = readMetadata(root).provider ?? "github";
             const message = provider === "linear"
@@ -975,7 +975,10 @@ export default function Dashboard() {
         }
         if (input === "r") {
             setState({ ...state, refreshing: true });
-            void refresh();
+            // Manual refresh bypasses the Linear snapshot cache: the user pressed
+            // `r` to see a change they just made externally (e.g. a freshly
+            // assigned ticket), so serving cached data would defeat the gesture.
+            void refresh({ forceRefresh: true });
             return;
         }
         // Orchestrate tab: Space toggles the ticket under the cursor; `a`

package/dist/lib/dashboard.d.ts

@@ -1,8 +1,8 @@
 import { type AheadBehind } from "./git.js";
 import { type PrInfo } from "./pr.js";
-import type { IssueProjectInfo, ProviderIssue } from "./providers/types.js";
+import type { IssueProjectInfo, LoadOptions, ProviderIssue } from "./providers/types.js";
 export type { PrInfo, PrState } from "./pr.js";
-export type { ProviderIssue, IssueProjectInfo, IssueId } from "./providers/types.js";
+export type { ProviderIssue, IssueProjectInfo, IssueId, LoadOptions } from "./providers/types.js";
 export type WorktreeInfo = {
     path: string;
     branch: string | null;
@@ -29,4 +29,4 @@ export type DashboardIssue = {
  * session snapshot. Designed to be called on dashboard mount and on every
  * `r` refresh — cheap because all the per-worktree probes are local.
  */
-export declare function loadDashboard(repoRoot: string): Promise<DashboardIssue[] | null>;
+export declare function loadDashboard(repoRoot: string, opts?: LoadOptions): Promise<DashboardIssue[] | null>;

package/dist/lib/dashboard.js

@@ -171,9 +171,9 @@ function buildOrphanRows(worktreesByIssue, assignedIds, sessionLookup, prByBranc
  * session snapshot. Designed to be called on dashboard mount and on every
  * `r` refresh — cheap because all the per-worktree probes are local.
  */
-export async function loadDashboard(repoRoot) {
+export async function loadDashboard(repoRoot, opts) {
     const provider = createProvider(repoRoot);
-    const issues = await provider.listAssignedIssues();
+    const issues = await provider.listAssignedIssues(opts);
     if (!issues)
         return null;
     const worktreesByIssue = buildWorktreeIndex(repoRoot);
@@ -196,7 +196,7 @@ export async function loadDashboard(repoRoot) {
     // alongside the per-branch PR probes so neither blocks the other.
     const [, projectByIssue] = await Promise.all([
         Promise.all(prFetches),
-        provider.fetchProjectAssignments(),
+        provider.fetchProjectAssignments(opts),
     ]);
     // Provider signals total failure (vs no projects configured) with null —
     // treat as a partial load failure so the caller's resilient refresh

package/dist/lib/metadata.d.ts

@@ -30,6 +30,7 @@ export type Metadata = {
     defaultPermissionMode?: PermissionMode;
     promptTemplate?: string;
     orchestratorPromptTemplate?: string;
+    linkFiles?: string[];
 };
 export declare function readMetadata(repoRoot: string): Metadata;
 export declare function writeMetadata(repoRoot: string, data: Metadata): void;

package/dist/lib/metadata.js

@@ -1,4 +1,5 @@
 import * as fs from "fs";
+import * as path from "path";
 import { getMetadataPath } from "./git.js";
 import { PERMISSION_MODES } from "./claude.js";
 const EMPTY = { version: 1, issues: {} };
@@ -16,6 +17,36 @@ function sanitizePromptTemplate(raw) {
 function sanitizeOrchestratorPromptTemplate(raw) {
     return typeof raw === "string" && raw.trim().length > 0 ? raw : undefined;
 }
+/**
+ * Keeps only safe, repo-root-relative paths. Drops non-strings, blanks,
+ * absolute paths and any entry that escapes the repo root via `..` — a
+ * malicious / fat-fingered `metadata.json` must never make mintree symlink
+ * something outside the worktree. Normalises and de-dupes the survivors.
+ */
+function sanitizeLinkFiles(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    const seen = new Set();
+    for (const v of raw) {
+        if (typeof v !== "string")
+            continue;
+        const trimmed = v.trim();
+        if (trimmed.length === 0 || path.isAbsolute(trimmed))
+            continue;
+        const norm = path.normalize(trimmed);
+        if (norm === ".." ||
+            norm.startsWith(`..${path.sep}`) ||
+            norm.includes(`${path.sep}..${path.sep}`)) {
+            continue;
+        }
+        if (seen.has(norm))
+            continue;
+        seen.add(norm);
+        out.push(norm);
+    }
+    return out.length > 0 ? out : undefined;
+}
 function sanitizeLinearTeam(raw) {
     if (typeof raw !== "object" || raw === null)
         return undefined;
@@ -90,6 +121,7 @@ export function readMetadata(repoRoot) {
         const defaultPermissionMode = sanitizePermissionMode(parsed.defaultPermissionMode);
         const promptTemplate = sanitizePromptTemplate(parsed.promptTemplate);
         const orchestratorPromptTemplate = sanitizeOrchestratorPromptTemplate(parsed.orchestratorPromptTemplate);
+        const linkFiles = sanitizeLinkFiles(parsed.linkFiles);
         return {
             version: 1,
             issues: typeof parsed.issues === "object" && parsed.issues !== null
@@ -101,6 +133,7 @@ export function readMetadata(repoRoot) {
             ...(defaultPermissionMode ? { defaultPermissionMode } : {}),
             ...(promptTemplate ? { promptTemplate } : {}),
             ...(orchestratorPromptTemplate ? { orchestratorPromptTemplate } : {}),
+            ...(linkFiles ? { linkFiles } : {}),
         };
     }
     catch {

package/dist/lib/providers/linear.d.ts

@@ -14,7 +14,7 @@
  * Linear personal API keys (`lin_api_...`) go directly into the
  * Authorization header with no `Bearer` prefix.
  */
-import type { IssueId, IssueProjectInfo, IssueProvider, ProviderIssue, TransitionResult } from "./types.js";
+import type { IssueId, IssueProjectInfo, IssueProvider, LoadOptions, ProviderIssue, TransitionResult } from "./types.js";
 export declare class LinearProvider implements IssueProvider {
     private readonly repoRoot;
     readonly kind: "linear";
@@ -26,10 +26,15 @@ export declare class LinearProvider implements IssueProvider {
      * and fetchProjectAssignments call this so we never double-fetch within a
      * load. Per-instance promise memoisation handles the back-to-back call;
      * the module-level cache handles refreshes within the TTL.
+     *
+     * `forceRefresh` skips the module-level cache read so the live GraphQL query
+     * runs again (it still writes the result back to the cache). The per-instance
+     * promise is kept either way, so the two callers within one load share the
+     * single forced fetch instead of issuing two.
      */
     private loadSnapshot;
-    listAssignedIssues(): Promise<ProviderIssue[] | null>;
-    fetchProjectAssignments(): Promise<Map<IssueId, IssueProjectInfo> | null>;
+    listAssignedIssues(opts?: LoadOptions): Promise<ProviderIssue[] | null>;
+    fetchProjectAssignments(opts?: LoadOptions): Promise<Map<IssueId, IssueProjectInfo> | null>;
     transitionIssueToInProgress(issueId: IssueId): Promise<TransitionResult>;
 }
 /**

package/dist/lib/providers/linear.js

@@ -355,8 +355,13 @@ export class LinearProvider {
      * and fetchProjectAssignments call this so we never double-fetch within a
      * load. Per-instance promise memoisation handles the back-to-back call;
      * the module-level cache handles refreshes within the TTL.
+     *
+     * `forceRefresh` skips the module-level cache read so the live GraphQL query
+     * runs again (it still writes the result back to the cache). The per-instance
+     * promise is kept either way, so the two callers within one load share the
+     * single forced fetch instead of issuing two.
      */
-    async loadSnapshot() {
+    async loadSnapshot(forceRefresh = false) {
         if (this.snapshotPromise)
             return this.snapshotPromise;
         const cfg = this.getConfig();
@@ -377,7 +382,7 @@ export class LinearProvider {
         }
         const apiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
         const teamKeys = cfg.teams.map((t) => t.key);
-        const cached = readSnapshotCache(cfg.workspaceSlug, teamKeys);
+        const cached = forceRefresh ? null : readSnapshotCache(cfg.workspaceSlug, teamKeys);
         if (cached)
             return cached;
         this.snapshotPromise = (async () => {
@@ -394,11 +399,11 @@ export class LinearProvider {
         })();
         return this.snapshotPromise;
     }
-    async listAssignedIssues() {
+    async listAssignedIssues(opts) {
         const cfg = this.getConfig();
         if (!cfg || cfg.teams.length === 0)
             return [];
-        const snapshot = await this.loadSnapshot();
+        const snapshot = await this.loadSnapshot(opts?.forceRefresh ?? false);
         if ("ok" in snapshot && snapshot.ok === false)
             return null;
         const data = snapshot;
@@ -417,12 +422,12 @@ export class LinearProvider {
         }
         return out;
     }
-    async fetchProjectAssignments() {
+    async fetchProjectAssignments(opts) {
         const cfg = this.getConfig();
         const result = new Map();
         if (!cfg || cfg.teams.length === 0)
             return result;
-        const snapshot = await this.loadSnapshot();
+        const snapshot = await this.loadSnapshot(opts?.forceRefresh ?? false);
         if ("ok" in snapshot && snapshot.ok === false)
             return null;
         const data = snapshot;

package/dist/lib/providers/types.d.ts

@@ -10,6 +10,17 @@
  * worktree dir names round-trip through the IssueId without re-parsing.
  */
 export type IssueId = string;
+/**
+ * Options shared by the read methods of IssueProvider. `forceRefresh` tells a
+ * provider that keeps a snapshot cache (Linear) to bypass it and re-fetch from
+ * the source. The dashboard sets it for the manual `r` refresh so a change made
+ * seconds ago (e.g. an issue just assigned to the user) shows up immediately,
+ * instead of waiting out the cache TTL. Providers without a cache (GitHub)
+ * ignore it.
+ */
+export type LoadOptions = {
+    forceRefresh?: boolean;
+};
 /**
  * A workflow issue normalised across providers. Shape mirrors what the GH
  * `gh issue list --json` payload exposes minus the GH-specific `number`
@@ -91,7 +102,7 @@ export interface IssueProvider {
      * Linear: the configured workspace/teams). Returns null on transient
      * failure (auth, network) — the dashboard renders an error hint.
      */
-    listAssignedIssues(): Promise<ProviderIssue[] | null>;
+    listAssignedIssues(opts?: LoadOptions): Promise<ProviderIssue[] | null>;
     /**
      * Returns project/board membership for the assigned issues (same scope as
      * listAssignedIssues — typically a single round-trip). The dashboard uses
@@ -104,7 +115,7 @@ export interface IssueProvider {
      *     auth missing). Distinct from empty so the dashboard can treat
      *     null as a partial load failure and keep its last-good state.
      */
-    fetchProjectAssignments(): Promise<Map<IssueId, IssueProjectInfo> | null>;
+    fetchProjectAssignments(opts?: LoadOptions): Promise<Map<IssueId, IssueProjectInfo> | null>;
     /**
      * Moves the issue to its project's "In Progress" workflow state. Idempotent
      * by design (returns noop-already when already there) and conservative on

package/dist/lib/worktreeCreate.js

@@ -49,6 +49,59 @@ function tryRunInitScript(scriptPath, worktreePath, repoRoot) {
         };
     }
 }
+/**
+ * Symlinks each `metadata.linkFiles` entry from the main repo into the freshly
+ * created worktree. Git worktrees don't share untracked files, so gitignored
+ * config like `.env` is absent in a new worktree; this links it in so the
+ * worktree's tooling finds the same secrets/config as the main checkout.
+ *
+ * A symlink (not a copy) keeps a single source of truth — rotating a credential
+ * in the main `.env` is seen by every worktree, and `worktree remove` deletes
+ * only the link. Entries are repo-root-relative (already validated by
+ * `sanitizeLinkFiles`). Each entry is best-effort: a missing source or an
+ * already-present target is skipped, never fatal.
+ */
+function linkFilesIntoWorktree(repoRoot, worktreePath, linkFiles, pushStep) {
+    for (const rel of linkFiles) {
+        const source = path.join(repoRoot, rel);
+        const target = path.join(worktreePath, rel);
+        if (!pathExists(source)) {
+            pushStep({ kind: "skip", label: `skipped link ${rel}`, detail: "not present in repo root" });
+            continue;
+        }
+        // lstat (not pathExists) so an existing symlink/file/dir already at the
+        // target — e.g. a tracked file git checked out — counts as present and
+        // we don't clobber it.
+        let targetTaken = false;
+        try {
+            fs.lstatSync(target);
+            targetTaken = true;
+        }
+        catch {
+            targetTaken = false;
+        }
+        if (targetTaken) {
+            pushStep({
+                kind: "skip",
+                label: `skipped link ${rel}`,
+                detail: "already present in worktree",
+            });
+            continue;
+        }
+        try {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.symlinkSync(source, target);
+            pushStep({ kind: "ok", label: `linked ${rel}`, detail: `→ ${source}` });
+        }
+        catch (err) {
+            pushStep({
+                kind: "warn",
+                label: `failed to link ${rel}`,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
 /**
  * Stashes a `--prompt` value into a temp file so the shell wrapper can hand
  * it back to `worktree work` via `--prompt-file`. Plain stdout markers can't
@@ -207,6 +260,13 @@ export async function runCreate(branchArg, opts) {
     upsertIssue(root, parsed.issueId, base ? { base_branch: base } : {});
     pushStep({ kind: "ok", label: "metadata updated", detail: `issue ${parsed.issueId}` });
     await nextFrame(progress);
+    // Link gitignored config (e.g. .env) before init.sh, so the hook can rely
+    // on those files being present.
+    const linkFiles = readMetadata(root).linkFiles;
+    if (linkFiles && linkFiles.length > 0) {
+        linkFilesIntoWorktree(root, worktreePath, linkFiles, pushStep);
+        await nextFrame(progress);
+    }
     const initShPath = getInitScriptPath(root);
     if (pathExists(initShPath)) {
         progress?.onPending?.("Running .mintree/init.sh...");
@@ -362,6 +422,13 @@ export async function runCreateDetached(opts) {
     upsertIssue(root, opts.issueId, { base_branch: currentBranch });
     pushStep({ kind: "ok", label: "metadata updated", detail: `issue ${opts.issueId}` });
     await nextFrame(progress);
+    // Link gitignored config (e.g. .env) before init.sh, so the hook can rely
+    // on those files being present.
+    const linkFiles = readMetadata(root).linkFiles;
+    if (linkFiles && linkFiles.length > 0) {
+        linkFilesIntoWorktree(root, worktreePath, linkFiles, pushStep);
+        await nextFrame(progress);
+    }
     const initShPath = getInitScriptPath(root);
     if (pathExists(initShPath)) {
         progress?.onPending?.("Running .mintree/init.sh...");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.5.11",
+	"version": "0.5.13",
 	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
 	"license": "MIT",
 	"author": "Martin Mineo <mmineo@canarytechnologies.com>",