personal-backlog 0.3.3__py3-none-any.whl

personal_backlog/__init__.py

@@ -0,0 +1,3 @@
+"""A tiny, Git-friendly Markdown backlog."""
+
+__version__ = "0.3.3"

personal_backlog/__main__.py

@@ -0,0 +1,5 @@
+from personal_backlog.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

personal_backlog/assistant.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from contextlib import ExitStack
+from dataclasses import dataclass
+import hashlib
+from importlib.resources import as_file, files
+import json
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+from typing import Protocol
+
+from personal_backlog.model import BacklogError, Task, ValidationError
+from personal_backlog.storage import current_release, list_tasks, now_iso, release_sort_key
+
+
+class AssistantError(BacklogError):
+    """A local AI provider could not produce a safe task proposal."""
+
+
+@dataclass(frozen=True, slots=True)
+class AssistantContext:
+    request: str
+    current_release: str | None
+    releases: tuple[str, ...]
+    existing_titles: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TaskProposal:
+    title: str
+    release: str | None
+    priority: int
+    size: str | None
+    body: str
+
+    def validate(self, context: AssistantContext) -> None:
+        if self.release is not None and self.release not in context.releases:
+            raise AssistantError(
+                f"provider proposed unknown release {self.release!r}; choose one of: "
+                f"{', '.join(context.releases) or 'none'}"
+            )
+        task = Task(
+            id="T0000",
+            title=self.title.strip(),
+            release=self.release,
+            priority=self.priority,
+            size=self.size,
+            state="todo",
+            created=now_iso(),
+            done=None,
+            body=self.body.strip("\n"),
+        )
+        try:
+            task.validate()
+        except ValidationError as exc:
+            raise AssistantError(f"provider returned an invalid task: {exc}") from exc
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "title": self.title.strip(),
+            "release": self.release,
+            "priority": self.priority,
+            "size": self.size,
+            "state": "todo",
+            "body": self.body.strip("\n"),
+        }
+
+
+class AssistantProvider(Protocol):
+    name: str
+
+    def propose(self, context: AssistantContext) -> TaskProposal:
+        """Produce one proposal without writing to the backlog."""
+
+
+def context_for(backlog_dir: Path, request: str) -> AssistantContext:
+    tasks = list_tasks(backlog_dir)
+    releases = tuple(sorted({task.release for task in tasks if task.release}, key=release_sort_key))
+    return AssistantContext(
+        request=request,
+        current_release=current_release(backlog_dir),
+        releases=releases,
+        existing_titles=tuple(task.title for task in tasks),
+    )
+
+
+class AppleIntelligenceProvider:
+    """Foundation Models bridge for the on-device Apple Intelligence model."""
+
+    name = "apple-intelligence"
+
+    def _helper_path(self) -> Path:
+        source = files("personal_backlog.assistant_assets").joinpath("apple_intelligence.swift")
+        with ExitStack() as stack:
+            source_path = stack.enter_context(as_file(source))
+            digest = hashlib.sha256(source_path.read_bytes()).hexdigest()[:16]
+            helper = Path(tempfile.gettempdir()) / f"personal-backlog-apple-intelligence-{digest}"
+            if helper.is_file() and os.access(helper, os.X_OK):
+                return helper
+            temporary = helper.with_name(f".{helper.name}-{os.getpid()}")
+            result = subprocess.run(
+                ["xcrun", "swiftc", "-parse-as-library", str(source_path), "-o", str(temporary)],
+                capture_output=True,
+                check=False,
+                text=True,
+            )
+            if result.returncode:
+                temporary.unlink(missing_ok=True)
+                message = result.stderr.strip() or result.stdout.strip() or "unknown compiler error"
+                raise AssistantError(f"could not prepare Apple Intelligence provider: {message}")
+            os.replace(temporary, helper)
+            helper.chmod(0o700)
+            return helper
+
+    def propose(self, context: AssistantContext) -> TaskProposal:
+        payload = {
+            "request": context.request,
+            "currentRelease": context.current_release,
+            "releases": list(context.releases),
+            "existingTitles": list(context.existing_titles),
+        }
+        try:
+            result = subprocess.run(
+                [str(self._helper_path())],
+                input=json.dumps(payload),
+                capture_output=True,
+                check=False,
+                text=True,
+                timeout=90,
+            )
+        except OSError as exc:
+            raise AssistantError(f"could not run Apple Intelligence provider: {exc}") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise AssistantError("Apple Intelligence provider timed out") from exc
+        if result.returncode:
+            message = result.stderr.strip() or result.stdout.strip() or "unknown provider error"
+            raise AssistantError(message.removeprefix("Apple Intelligence provider error: ").strip())
+        try:
+            generated = json.loads(result.stdout)
+            release = generated["release"].strip()
+            proposal = TaskProposal(
+                title=generated["title"],
+                release=None if release.casefold() in {"none", "null", "-"} else release,
+                priority=generated["priority"],
+                size=generated["size"],
+                body=generated["body"],
+            )
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise AssistantError("Apple Intelligence provider returned an invalid structured response") from exc
+        proposal.validate(context)
+        return proposal
+
+
+def get_provider(name: str) -> AssistantProvider:
+    providers: dict[str, AssistantProvider] = {AppleIntelligenceProvider.name: AppleIntelligenceProvider()}
+    try:
+        return providers[name]
+    except KeyError as exc:
+        raise AssistantError(
+            f"unknown assistant provider {name!r}; available providers: {', '.join(sorted(providers))}"
+        ) from exc

personal_backlog/assistant_assets/__init__.py

@@ -0,0 +1 @@
+"""Local AI provider helper assets."""

personal_backlog/assistant_assets/apple_intelligence.swift

@@ -0,0 +1,84 @@
+import Foundation
+import FoundationModels
+
+struct AssistantInput: Decodable {
+    let request: String
+    let currentRelease: String?
+    let releases: [String]
+    let existingTitles: [String]
+}
+
+@Generable
+struct GeneratedTask {
+    @Guide(description: "A concise, imperative, single-line task title.")
+    var title: String
+
+    @Guide(description: "One of the available release strings, or the literal word none when unassigned.")
+    var release: String
+
+    @Guide(description: "A priority from 1 (highest) through 5 (parked).")
+    var priority: Int
+
+    @Guide(description: "Exactly one of S, M, or L. S is isolated work, M is related work in one layer, and L is cross-cutting work.")
+    var size: String
+
+    @Guide(description: "A useful Markdown task body with Context, Desired outcome, Decisions and constraints, and Acceptance criteria headings.")
+    var body: String
+}
+
+struct Output: Encodable {
+    let title: String
+    let release: String
+    let priority: Int
+    let size: String
+    let body: String
+}
+
+@main
+struct BacklogAppleIntelligence {
+    static func main() async {
+        do {
+            let inputData = FileHandle.standardInput.readDataToEndOfFile()
+            let input = try JSONDecoder().decode(AssistantInput.self, from: inputData)
+            let model = SystemLanguageModel.default
+            guard case .available = model.availability else {
+                throw NSError(domain: "PersonalBacklog", code: 1, userInfo: [
+                    NSLocalizedDescriptionKey: "Apple Intelligence is unavailable on this Mac. Enable it and wait for the on-device model to finish downloading."
+                ])
+            }
+            let releaseList = input.releases.isEmpty ? "none" : input.releases.joined(separator: ", ")
+            let currentRelease = input.currentRelease ?? "none"
+            let knownTasks = input.existingTitles.prefix(60).joined(separator: " | ")
+            let instructions = """
+            You turn a person's natural-language request into exactly one Personal Backlog task.
+            Generate a proposal only; never claim that you created, changed, or completed a task.
+            Use priority 1 for top priority. Choose a release from the supplied available releases; use none only when the request does not relate to a release.
+            The body must be concise Markdown. Do not include secrets, credentials, or personal data.
+            """
+            let prompt = """
+            Person's request:
+            \(input.request)
+
+            Current release: \(currentRelease)
+            Available releases: \(releaseList)
+            Existing task titles, for avoiding duplicates: \(knownTasks)
+            """
+            let session = LanguageModelSession(model: model, instructions: instructions)
+            let response = try await session.respond(to: prompt, generating: GeneratedTask.self)
+            let proposal = response.content
+            let output = Output(
+                title: proposal.title,
+                release: proposal.release,
+                priority: proposal.priority,
+                size: proposal.size,
+                body: proposal.body
+            )
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.sortedKeys]
+            print(String(data: try encoder.encode(output), encoding: .utf8)!)
+        } catch {
+            FileHandle.standardError.write(Data("Apple Intelligence provider error: \(error.localizedDescription)\n".utf8))
+            exit(2)
+        }
+    }
+}

personal_backlog/board.py

@@ -0,0 +1,19 @@
+"""Compatibility adapter for the backlog board."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from http.server import ThreadingHTTPServer
+
+from personal_backlog.server import create_server, serve
+
+
+def create_board_server(backlog_dir: Path, port: int = 8766) -> ThreadingHTTPServer:
+    """Create a server in read-only mode for backward compatibility."""
+    return create_server(backlog_dir, port=port, read_only=True)
+
+
+def serve_board(backlog_dir: Path, *, port: int = 8766, open_browser: bool = True) -> None:
+    """Serve the backlog in read-only mode for backward compatibility."""
+    serve(backlog_dir, port=port, open_browser=open_browser, read_only=True)
+

personal_backlog/board_web/__init__.py

@@ -0,0 +1 @@
+"""Static assets for the read-only task board."""

personal_backlog/board_web/app.js

@@ -0,0 +1,155 @@
+const states = [
+  { key: "todo", cards: "todo-cards", count: "todo-count" },
+  { key: "in_progress", cards: "in-progress-cards", count: "in-progress-count" },
+  { key: "done", cards: "done-cards", count: "done-count" },
+];
+
+const elements = {
+  project: document.querySelector("#project-name"),
+  path: document.querySelector("#backlog-path"),
+  release: document.querySelector("#release-filter"),
+  refresh: document.querySelector("#refresh"),
+  summary: document.querySelector("#summary"),
+  version: document.querySelector("#version"),
+  template: document.querySelector("#task-card-template"),
+  dialog: document.querySelector("#task-dialog"),
+  detail: document.querySelector("#task-detail"),
+};
+
+let tasks = [];
+let defaultRelease = null;
+let defaultReleaseApplied = false;
+
+async function api(path) {
+  const response = await fetch(path);
+  const payload = await response.json();
+  if (!response.ok) throw new Error(payload.error || `Request failed (${response.status})`);
+  return payload;
+}
+
+function releaseKey(task) {
+  return task.release ?? "__none__";
+}
+
+function releaseLabel(release) {
+  return release === "__none__" ? "Unassigned" : release;
+}
+
+function compareReleases(a, b) {
+  if (a === "__none__") return 1;
+  if (b === "__none__") return -1;
+  if (a === "next") return 1;
+  if (b === "next") return -1;
+  return a.localeCompare(b, undefined, { numeric: true });
+}
+
+function renderReleaseFilter() {
+  const selected = elements.release.value;
+  const releases = [...new Set(tasks.map(releaseKey))].sort(compareReleases);
+  elements.release.replaceChildren(new Option("All releases", ""));
+  releases.forEach((release) => {
+    elements.release.add(new Option(releaseLabel(release), release));
+  });
+  if (releases.includes(selected)) {
+    elements.release.value = selected;
+  } else if (!defaultReleaseApplied && defaultRelease && releases.includes(defaultRelease)) {
+    elements.release.value = defaultRelease;
+  }
+  defaultReleaseApplied = true;
+}
+
+function taskCard(task) {
+  const card = elements.template.content.firstElementChild.cloneNode(true);
+  card.dataset.priority = task.priority;
+  card.tabIndex = 0;
+  card.setAttribute("role", "button");
+  card.setAttribute("aria-label", `Show details for ${task.title}`);
+  card.addEventListener("click", () => openTask(task.id));
+  card.addEventListener("keydown", (event) => {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      openTask(task.id);
+    }
+  });
+  card.querySelector(".task-id").textContent = task.id;
+  card.querySelector(".priority").textContent = `P${task.priority}`;
+  card.querySelector("h3").textContent = task.title;
+  card.querySelector(".release").textContent = task.release || "Unassigned";
+  card.querySelector(".size").textContent = task.size || "—";
+  if (task.tags?.length) {
+    const tags = card.querySelector(".tags");
+    tags.hidden = false;
+    tags.querySelector("dd").textContent = task.tags.join(", ");
+  }
+  return card;
+}
+
+async function openTask(id) {
+  try {
+    const task = await api(`/api/tasks/${encodeURIComponent(id)}`);
+    window.PersonalBacklogTaskDetail.render(elements.detail, task, {
+      onClose: () => elements.dialog.close(),
+    });
+    elements.dialog.showModal();
+  } catch (error) {
+    elements.summary.textContent = error.message;
+    elements.summary.classList.add("error");
+  }
+}
+
+function emptyLane() {
+  const empty = document.createElement("p");
+  empty.className = "empty-lane";
+  empty.textContent = "No tasks here.";
+  return empty;
+}
+
+function renderBoard() {
+  const selectedRelease = elements.release.value;
+  const visible = tasks.filter((task) => !selectedRelease || releaseKey(task) === selectedRelease);
+
+  states.forEach((state) => {
+    const laneTasks = visible.filter((task) => task.state === state.key);
+    const container = document.querySelector(`#${state.cards}`);
+    document.querySelector(`#${state.count}`).textContent = laneTasks.length;
+    container.replaceChildren(...(laneTasks.length ? laneTasks.map(taskCard) : [emptyLane()]));
+  });
+
+  const releaseText = selectedRelease ? ` in ${releaseLabel(selectedRelease)}` : "";
+  elements.summary.textContent = `${visible.length} task${visible.length === 1 ? "" : "s"}${releaseText} · 3 states`;
+}
+
+async function refresh() {
+  elements.refresh.disabled = true;
+  elements.refresh.textContent = "Refreshing…";
+  try {
+    tasks = await api("/api/tasks");
+    renderReleaseFilter();
+    renderBoard();
+  } catch (error) {
+    elements.summary.textContent = error.message;
+    elements.summary.classList.add("error");
+  } finally {
+    elements.refresh.disabled = false;
+    elements.refresh.textContent = "Refresh";
+  }
+}
+
+elements.release.addEventListener("change", renderBoard);
+elements.refresh.addEventListener("click", refresh);
+
+Promise.all([api("/api/meta"), refresh()])
+  .then(([meta]) => {
+    defaultRelease = meta.current_release || null;
+    defaultReleaseApplied = false;
+    renderReleaseFilter();
+    renderBoard();
+    elements.project.textContent = meta.project || "Project";
+    elements.path.textContent = meta.backlog;
+    elements.version.textContent = `· v${meta.version}`;
+    document.title = `${meta.project || "Backlog"} board`;
+  })
+  .catch((error) => {
+    elements.summary.textContent = error.message;
+    elements.summary.classList.add("error");
+  });

personal_backlog/board_web/index.html

@@ -0,0 +1,102 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="description" content="A read-only three-column view of a Personal Backlog.">
+    <title>Backlog board</title>
+    <link rel="stylesheet" href="/styles.css">
+    <link rel="stylesheet" href="/task-detail.css">
+  </head>
+  <body>
+    <header class="masthead">
+      <div class="identity">
+        <p class="eyebrow">PERSONAL BACKLOG</p>
+        <h1><span id="project-name">Project</span> board</h1>
+        <p id="backlog-path" class="path">Loading backlog…</p>
+      </div>
+
+      <div class="controls" aria-label="Board controls">
+        <label for="release-filter">Release</label>
+        <div class="control-row">
+          <select id="release-filter">
+            <option value="">All releases</option>
+          </select>
+          <button id="refresh" type="button">Refresh</button>
+        </div>
+        <p id="summary" class="summary" aria-live="polite">Loading tasks…</p>
+      </div>
+    </header>
+
+    <main class="board" aria-label="Task board">
+      <section class="lane lane-todo" aria-labelledby="todo-heading">
+        <header class="lane-heading">
+          <div>
+            <p class="lane-kicker"><span class="status-dot"></span>Queue</p>
+            <h2 id="todo-heading">Todo</h2>
+          </div>
+          <span id="todo-count" class="lane-count">0</span>
+        </header>
+        <div id="todo-cards" class="cards"></div>
+      </section>
+
+      <section class="lane lane-in-progress" aria-labelledby="in-progress-heading">
+        <header class="lane-heading">
+          <div>
+            <p class="lane-kicker"><span class="status-dot"></span>Active</p>
+            <h2 id="in-progress-heading">In progress</h2>
+          </div>
+          <span id="in-progress-count" class="lane-count">0</span>
+        </header>
+        <div id="in-progress-cards" class="cards"></div>
+      </section>
+
+      <section class="lane lane-done" aria-labelledby="done-heading">
+        <header class="lane-heading">
+          <div>
+            <p class="lane-kicker"><span class="status-dot"></span>Complete</p>
+            <h2 id="done-heading">Done</h2>
+          </div>
+          <span id="done-count" class="lane-count">0</span>
+        </header>
+        <div id="done-cards" class="cards"></div>
+      </section>
+    </main>
+
+    <footer>
+      <p><span class="read-only-mark" aria-hidden="true"></span>Read only</p>
+      <p>Markdown remains the source of truth <span id="version"></span></p>
+    </footer>
+
+    <template id="task-card-template">
+      <article class="task-card">
+        <div class="card-topline">
+          <span class="task-id"></span>
+          <span class="priority"></span>
+        </div>
+        <h3></h3>
+        <dl class="task-meta">
+          <div>
+            <dt>Release</dt>
+            <dd class="release"></dd>
+          </div>
+          <div>
+            <dt>Size</dt>
+            <dd class="size"></dd>
+          </div>
+          <div class="tags" hidden>
+            <dt>Tags</dt>
+            <dd></dd>
+          </div>
+        </dl>
+      </article>
+    </template>
+
+    <dialog id="task-dialog" class="task-dialog" aria-label="Task details">
+      <div id="task-detail"></div>
+    </dialog>
+
+    <script src="/task-detail.js" defer></script>
+    <script src="/app.js" defer></script>
+  </body>
+</html>