santree 0.6.2 → 0.7.0

package/dist/lib/trackers/local/store.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getSantreeDir, readAllMetadata, writeAllMetadata } from "../../metadata.js";
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+// On-disk layout: one Markdown file per issue under `.santree/issues/`,
+// named `<ID>.md` (e.g. `LOCAL-1.md`). `.santree/issues/` is NOT in
+// .gitignore (which only excludes worktrees/metadata.json/session-states),
+// so issue files are version-controlled by default — the whole point of the
+// built-in tracker.
+//
+// Comments are intentionally not modeled in v1: Local issues always carry
+// `comments: []`. The Issue type already permits an empty array.
+export const ID_PREFIX = "LOCAL";
+const FILE_RE = /^LOCAL-(\d+)\.md$/;
+export function getIssuesDir(repoRoot) {
+    return path.join(getSantreeDir(repoRoot), "issues");
+}
+export function ensureIssuesDir(repoRoot) {
+    const dir = getIssuesDir(repoRoot);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+function issueFilePath(repoRoot, identifier) {
+    return path.join(getIssuesDir(repoRoot), `${identifier}.md`);
+}
+/** Map a Linear-style numeric priority to a human label. 0 == no priority. */
+export function priorityLabel(priority) {
+    switch (priority) {
+        case 1:
+            return "Urgent";
+        case 2:
+            return "High";
+        case 3:
+            return "Medium";
+        case 4:
+            return "Low";
+        default:
+            return "None";
+    }
+}
+function recordToIssue(data, body) {
+    const identifier = typeof data["id"] === "string" ? data["id"] : null;
+    if (!identifier || !FILE_RE.test(`${identifier}.md`))
+        return null;
+    const title = typeof data["title"] === "string" ? data["title"] : String(data["title"] ?? "");
+    const priority = typeof data["priority"] === "number" ? data["priority"] : 0;
+    const labels = Array.isArray(data["labels"]) ? data["labels"] : [];
+    const stateName = typeof data["state"] === "string" ? data["state"] : "Todo";
+    const stateType = typeof data["stateType"] === "string" ? data["stateType"] : "unstarted";
+    const description = body.trim() === "" ? null : body;
+    return {
+        identifier,
+        title,
+        description,
+        url: "", // Local issues have no web URL — the dashboard hides the [o] action.
+        priority,
+        priorityLabel: typeof data["priorityLabel"] === "string" ? data["priorityLabel"] : priorityLabel(priority),
+        state: { name: stateName, type: stateType },
+        labels,
+        projectId: null,
+        projectName: null,
+        comments: [],
+    };
+}
+function issueToRecord(issue, createdAt) {
+    return {
+        data: {
+            id: issue.identifier,
+            title: issue.title,
+            state: issue.state.name,
+            stateType: issue.state.type,
+            priority: issue.priority,
+            priorityLabel: issue.priorityLabel,
+            labels: issue.labels,
+            createdAt,
+        },
+        body: issue.description ?? "",
+    };
+}
+/** Read every well-formed issue file. Malformed files are skipped, never
+ * fatal. Returned newest-first by creation time (falling back to numeric ID). */
+export function listIssues(repoRoot) {
+    const dir = getIssuesDir(repoRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const m = name.match(FILE_RE);
+        if (!m)
+            continue;
+        try {
+            const raw = fs.readFileSync(path.join(dir, name), "utf-8");
+            const { data, body } = parseFrontmatter(raw);
+            const issue = recordToIssue(data, body);
+            if (!issue)
+                continue;
+            const createdAt = typeof data["createdAt"] === "string" ? data["createdAt"] : "";
+            out.push({ issue, createdAt, num: Number(m[1]) });
+        }
+        catch {
+            // Skip unreadable / corrupt file.
+        }
+    }
+    out.sort((a, b) => {
+        if (a.createdAt && b.createdAt && a.createdAt !== b.createdAt) {
+            return b.createdAt.localeCompare(a.createdAt);
+        }
+        return b.num - a.num;
+    });
+    return out.map((o) => o.issue);
+}
+export function readIssue(repoRoot, identifier) {
+    const file = issueFilePath(repoRoot, identifier);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const { data, body } = parseFrontmatter(fs.readFileSync(file, "utf-8"));
+        return recordToIssue(data, body);
+    }
+    catch {
+        return null;
+    }
+}
+/** Write (create or overwrite) an issue file. `createdAt` preserves the
+ * original timestamp on edits; pass a fresh ISO string when creating. */
+export function writeIssue(repoRoot, issue, createdAt) {
+    ensureIssuesDir(repoRoot);
+    const { data, body } = issueToRecord(issue, createdAt);
+    fs.writeFileSync(issueFilePath(repoRoot, issue.identifier), serializeFrontmatter(data, body));
+}
+/** Return the original `createdAt` for an existing issue, or "" if unknown. */
+export function readCreatedAt(repoRoot, identifier) {
+    const file = issueFilePath(repoRoot, identifier);
+    if (!fs.existsSync(file))
+        return "";
+    try {
+        const { data } = parseFrontmatter(fs.readFileSync(file, "utf-8"));
+        return typeof data["createdAt"] === "string" ? data["createdAt"] : "";
+    }
+    catch {
+        return "";
+    }
+}
+export function deleteIssueFile(repoRoot, identifier) {
+    const file = issueFilePath(repoRoot, identifier);
+    if (!fs.existsSync(file))
+        return false;
+    try {
+        fs.unlinkSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function maxExistingNum(repoRoot) {
+    const dir = getIssuesDir(repoRoot);
+    let max = 0;
+    if (fs.existsSync(dir)) {
+        try {
+            for (const name of fs.readdirSync(dir)) {
+                const m = name.match(FILE_RE);
+                if (m)
+                    max = Math.max(max, Number(m[1]));
+            }
+        }
+        catch {
+            // fall through with max = 0
+        }
+    }
+    return max;
+}
+/**
+ * Allocate the next issue ID and persist the high-water mark so numbers are
+ * monotonic and never recycled: deleting LOCAL-3 then creating again yields
+ * LOCAL-4, not LOCAL-3 — a stale local `feature/LOCAL-3-*` branch/worktree
+ * can't collide with a reused ID.
+ *
+ * The counter lives in `.santree/metadata.json` (`_local.lastId`), which is
+ * git-ignored and therefore per-machine. That's exactly the right scope: the
+ * collision we're avoiding is with *local* worktrees/branches. On a fresh
+ * clone metadata.json is absent, so the counter rebuilds from the committed
+ * issue files (max existing) — correct, since a fresh clone has no stale
+ * local worktrees.
+ */
+export function allocateId(repoRoot) {
+    const all = readAllMetadata(repoRoot);
+    const local = all["_local"] ?? {};
+    const last = typeof local.lastId === "number" ? local.lastId : 0;
+    const next = Math.max(last, maxExistingNum(repoRoot)) + 1;
+    all["_local"] = { ...local, lastId: next };
+    writeAllMetadata(repoRoot, all);
+    return `${ID_PREFIX}-${next}`;
+}

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

@@ -1,4 +1,4 @@
-export type IssueTrackerKind = "linear" | "github";
+export type IssueTrackerKind = "linear" | "github" | "local";
 export interface Comment {
     author: string;
     body: string;
@@ -39,6 +39,22 @@ export type IssueTrackerResult<T> = {
     reason: "unauthenticated" | "not-found" | "network";
     message?: string;
 };
+/** Fields accepted when creating a new issue. Only the built-in Local tracker
+ * supports mutation today (see `IssueTracker.canMutate`). */
+export interface NewIssueInput {
+    title: string;
+    description: string;
+    priority?: number;
+    labels?: string[];
+}
+/** Partial patch for an existing issue. Omitted fields are left unchanged. */
+export interface IssuePatch {
+    title?: string;
+    description?: string;
+    priority?: number;
+    labels?: string[];
+    state?: State;
+}
 export interface IssueTracker {
     readonly kind: IssueTrackerKind;
     readonly displayName: string;
@@ -49,4 +65,13 @@ export interface IssueTracker {
     cleanupCache(identifier: string): void;
     listAssigned(repoRoot: string): Promise<IssueTrackerResult<AssignedIssue[]>>;
     getIssue(identifier: string, repoRoot: string): Promise<IssueTrackerResult<Issue>>;
+    /** When true, the tracker implements createIssue/updateIssue/deleteIssue.
+     * Read-only trackers (Linear, GitHub) leave this undefined; UI surfaces
+     * gate every mutation path on `tracker.canMutate === true` (feature
+     * detection — never a `kind === "local"` string check, per the
+     * no-tracker-conditionals-outside-the-factory policy). */
+    readonly canMutate?: boolean;
+    createIssue?(input: NewIssueInput, repoRoot: string): Promise<IssueTrackerResult<Issue>>;
+    updateIssue?(identifier: string, patch: IssuePatch, repoRoot: string): Promise<IssueTrackerResult<Issue>>;
+    deleteIssue?(identifier: string, repoRoot: string): Promise<IssueTrackerResult<void>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "santree",
-	"version": "0.6.2",
+	"version": "0.7.0",
 	"description": "Git worktree manager",
 	"license": "MIT",
 	"author": "Santiago Toscanini",