@gitdocket/core 0.0.0 → 0.1.1

package/src/filestore.ts

@@ -0,0 +1,63 @@
+// FileStore abstracts where a bundle's files live. Local filesystem now;
+// a GitHub Git Data API implementation later lets the hosted App operate
+// without ever cloning a repo.
+
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface FileStore {
+  /** Relative paths (posix separators) of every .md file under the root, sorted. */
+  list(): Promise<string[]>;
+  read(path: string): Promise<string>;
+  write(path: string, content: string): Promise<void>;
+}
+
+export class LocalFileStore implements FileStore {
+  constructor(readonly root: string) {}
+
+  async list(): Promise<string[]> {
+    const out: string[] = [];
+    const walk = async (rel: string): Promise<void> => {
+      const entries = await readdir(join(this.root, rel), {
+        withFileTypes: true,
+      });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        const relPath = rel === "" ? entry.name : `${rel}/${entry.name}`;
+        if (entry.isDirectory()) await walk(relPath);
+        else if (entry.name.endsWith(".md")) out.push(relPath);
+      }
+    };
+    await walk("");
+    return out.sort();
+  }
+
+  read(path: string): Promise<string> {
+    return readFile(join(this.root, path), "utf8");
+  }
+
+  async write(path: string, content: string): Promise<void> {
+    const abs = join(this.root, path);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, content, "utf8");
+  }
+}
+
+/** Test double and future in-process cache seed. */
+export class InMemoryFileStore implements FileStore {
+  constructor(readonly files = new Map<string, string>()) {}
+
+  async list(): Promise<string[]> {
+    return [...this.files.keys()].filter((p) => p.endsWith(".md")).sort();
+  }
+
+  async read(path: string): Promise<string> {
+    const content = this.files.get(path);
+    if (content === undefined) throw new Error(`not found: ${path}`);
+    return content;
+  }
+
+  async write(path: string, content: string): Promise<void> {
+    this.files.set(path, content);
+  }
+}

package/src/id-allocation.ts

@@ -0,0 +1,288 @@
+// Optional local-Git coordination for sequential work-item creation. The core
+// create path accepts this boundary explicitly so in-memory, filesystem-only,
+// and future hosted stores keep deterministic max+1 behavior without needing
+// a system Git binary.
+
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { parseConfig } from "./config";
+import { LocalFileStore } from "./filestore";
+
+const execFileAsync = promisify(execFile);
+
+export interface WorkItemIdCoordinator {
+  allocate<T>(
+    project: string,
+    create: (knownIds: ReadonlySet<string>) => Promise<T>,
+  ): Promise<T>;
+}
+
+export interface GitWorktreeIdCoordinatorOptions {
+  lockTimeoutMs?: number;
+  staleLockMs?: number;
+  retryDelayMs?: number;
+}
+
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
+const DEFAULT_RETRY_DELAY_MS = 25;
+const LOCK_DIRECTORY = "docket/id-allocation.lock";
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+
+const errorCode = (error: unknown): string | undefined =>
+  typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+
+async function git(
+  repoRoot: string,
+  args: string[],
+): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync("git", ["-C", repoRoot, ...args], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+async function gitCommonDirectory(repoRoot: string): Promise<string | null> {
+  try {
+    const { stdout } = await git(repoRoot, ["rev-parse", "--git-common-dir"]);
+    const value = stdout.trim();
+    if (!value) throw new Error("git returned an empty common directory");
+    return isAbsolute(value) ? value : resolve(repoRoot, value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/not a git repository/i.test(message)) return null;
+    throw new Error(`cannot resolve Git common directory: ${message}`);
+  }
+}
+
+async function linkedWorktrees(repoRoot: string): Promise<string[]> {
+  const { stdout } = await git(repoRoot, [
+    "worktree",
+    "list",
+    "--porcelain",
+    "-z",
+  ]);
+  const paths = stdout
+    .split("\0")
+    .filter((line) => line.startsWith("worktree "))
+    .map((line) => line.slice("worktree ".length));
+  return [...new Set(paths)];
+}
+
+function readableWorkItemId(source: string): string | null {
+  const frontmatter = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!frontmatter?.[1]) return null;
+  const id = frontmatter[1].match(/^id:\s*['"]?([^\s'"#]+)['"]?\s*(?:#.*)?$/m);
+  return id?.[1] ?? null;
+}
+
+async function idsInWorktree(
+  worktree: string,
+  project: string,
+): Promise<string[]> {
+  let configSource: string;
+  try {
+    configSource = await readFile(join(worktree, "docket.yaml"), "utf8");
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      try {
+        await stat(worktree);
+      } catch (worktreeError) {
+        if (errorCode(worktreeError) === "ENOENT") {
+          throw new Error(
+            `linked worktree disappeared during ID allocation: ${worktree}; prune or restore it, then retry`,
+          );
+        }
+        throw worktreeError;
+      }
+      // A live worktree from before Docket adoption does not participate in
+      // this repository's work-item namespace.
+      return [];
+    }
+    throw error;
+  }
+
+  const config = parseConfig(configSource);
+  const store = new LocalFileStore(resolve(worktree, config.bundle));
+  let paths: string[];
+  try {
+    paths = await store.list();
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      throw new Error(
+        `cannot scan configured bundle ${config.bundle} in linked worktree ${worktree}; restore it or remove the stale worktree`,
+      );
+    }
+    throw error;
+  }
+
+  const ids: string[] = [];
+  for (const path of paths) {
+    if (!/^work\/(?:tasks|epics)\/.+\.md$/.test(path)) continue;
+    const source = await store.read(path).catch((error: unknown) => {
+      throw new Error(
+        `cannot read linked work item ${join(worktree, config.bundle, path)}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    });
+    const id = readableWorkItemId(source);
+    if (!id) {
+      throw new Error(
+        `cannot allocate an ID while linked work item ${join(worktree, config.bundle, path)} has no readable frontmatter id`,
+      );
+    }
+    if (id.startsWith(`${project}-`)) ids.push(id);
+  }
+  return ids;
+}
+
+async function repositoryIds(
+  repoRoot: string,
+  project: string,
+): Promise<Set<string>> {
+  const ids = new Set<string>();
+  for (const worktree of await linkedWorktrees(repoRoot)) {
+    for (const id of await idsInWorktree(worktree, project)) ids.add(id);
+  }
+  return ids;
+}
+
+interface LockOwner {
+  pid?: number;
+  host?: string;
+  startedAt?: string;
+}
+
+async function readOwner(lockDirectory: string): Promise<LockOwner | null> {
+  try {
+    return JSON.parse(
+      await readFile(join(lockDirectory, "owner.json"), "utf8"),
+    ) as LockOwner;
+  } catch {
+    return null;
+  }
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) === "EPERM";
+  }
+}
+
+async function lockIsStale(
+  lockDirectory: string,
+  staleLockMs: number,
+): Promise<boolean> {
+  const owner = await readOwner(lockDirectory);
+  if (
+    owner?.host === hostname() &&
+    typeof owner.pid === "number" &&
+    Number.isInteger(owner.pid)
+  ) {
+    return !processIsAlive(owner.pid);
+  }
+  const metadata = await stat(lockDirectory);
+  return Date.now() - metadata.mtimeMs >= staleLockMs;
+}
+
+async function acquireLock(
+  commonDirectory: string,
+  options: Required<GitWorktreeIdCoordinatorOptions>,
+): Promise<string> {
+  const parent = join(commonDirectory, "docket");
+  const lockDirectory = join(commonDirectory, LOCK_DIRECTORY);
+  await mkdir(parent, { recursive: true });
+  const started = Date.now();
+
+  for (;;) {
+    try {
+      await mkdir(lockDirectory);
+      await writeFile(
+        join(lockDirectory, "owner.json"),
+        `${JSON.stringify({
+          pid: process.pid,
+          host: hostname(),
+          startedAt: new Date().toISOString(),
+        })}\n`,
+        "utf8",
+      );
+      return lockDirectory;
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") throw error;
+
+      if (
+        await lockIsStale(lockDirectory, options.staleLockMs).catch(() => true)
+      ) {
+        const staleDirectory = `${lockDirectory}.stale-${process.pid}-${Date.now()}`;
+        try {
+          await rename(lockDirectory, staleDirectory);
+          await rm(staleDirectory, { recursive: true, force: true });
+          continue;
+        } catch (recoveryError) {
+          if (
+            errorCode(recoveryError) === "ENOENT" ||
+            errorCode(recoveryError) === "EEXIST"
+          ) {
+            continue;
+          }
+          throw new Error(
+            `cannot recover stale Docket ID-allocation lock ${lockDirectory}: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`,
+          );
+        }
+      }
+
+      if (Date.now() - started >= options.lockTimeoutMs) {
+        const owner = await readOwner(lockDirectory);
+        throw new Error(
+          `timed out after ${options.lockTimeoutMs}ms waiting for Docket ID-allocation lock ${lockDirectory}${owner ? ` (owner ${owner.host ?? "unknown"}:${owner.pid ?? "unknown"}, started ${owner.startedAt ?? "unknown"})` : ""}`,
+        );
+      }
+      await sleep(options.retryDelayMs);
+    }
+  }
+}
+
+/**
+ * Same-repository coordinator for LocalFileStore creation. The lock lives in
+ * Git's common directory, so every linked worktree uses one allocation
+ * boundary. The scan reads each live worktree's own docket.yaml and working
+ * files, which includes staged, unstaged, and untracked concepts.
+ */
+export class GitWorktreeIdCoordinator implements WorkItemIdCoordinator {
+  private readonly options: Required<GitWorktreeIdCoordinatorOptions>;
+
+  constructor(
+    private readonly repoRoot: string,
+    options: GitWorktreeIdCoordinatorOptions = {},
+  ) {
+    this.options = {
+      lockTimeoutMs: options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS,
+      staleLockMs: options.staleLockMs ?? DEFAULT_STALE_LOCK_MS,
+      retryDelayMs: options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
+    };
+  }
+
+  async allocate<T>(
+    project: string,
+    create: (knownIds: ReadonlySet<string>) => Promise<T>,
+  ): Promise<T> {
+    const commonDirectory = await gitCommonDirectory(this.repoRoot);
+    if (!commonDirectory) return create(new Set());
+
+    const lockDirectory = await acquireLock(commonDirectory, this.options);
+    try {
+      return await create(await repositoryIds(this.repoRoot, project));
+    } finally {
+      await rm(lockDirectory, { recursive: true, force: true });
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,199 @@
+// @gitdocket/core — the engine. Every surface (CLI, web, MCP, App) is a thin
+// client over this library; there is exactly one write path.
+
+export {
+  type Bundle,
+  findRepoRoot,
+  loadBundle,
+  loadRepo,
+  readyWorkItems,
+} from "./bundle";
+export {
+  CONFIG_FILENAME,
+  DEFAULT_BUNDLE,
+  type DocketConfig,
+  parseConfig,
+} from "./config";
+export {
+  ENGINE_SEMANTICS,
+  READY_QUEUE_DESCRIPTION,
+} from "./engine-semantics";
+export { type FileStore, InMemoryFileStore, LocalFileStore } from "./filestore";
+export {
+  GitWorktreeIdCoordinator,
+  type GitWorktreeIdCoordinatorOptions,
+  type WorkItemIdCoordinator,
+} from "./id-allocation";
+export { applyIndex, INDEX_MARKER, renderIndex } from "./indexmd";
+export {
+  ALLOW_RULES,
+  composeFreshnessBaseline,
+  composeHook,
+  defaultConfigYaml,
+  deriveProjectKey,
+  ensureGitignore,
+  type InitAction,
+  type InitResult,
+  mergeClaudeSettings,
+  mergeCodexConfig,
+  mergeMcpJson,
+  needsFrontmatter,
+  proposeType,
+  scaffoldFiles,
+  upgradeCodexConfig,
+  upgradeHookBlock,
+} from "./init";
+export {
+  AGENT_INTENT_DISAMBIGUATION,
+  AGENT_INTENT_IDS,
+  AGENT_INTENTS,
+  type AgentIntentContract,
+  type AgentIntentId,
+  agentIntent,
+  DIRECT_WORK_INTENT,
+  DIRECT_WORK_INTENT_ID,
+  DOCKET_INTENT_DISAMBIGUATION,
+  DOCKET_INTENT_IDS,
+  DOCKET_INTENTS,
+  type DocketIntentContract,
+  type DocketIntentId,
+  docketIntent,
+  type IntentEntrypoint,
+  type IntentMode,
+  PICKUP_AUTHORITY_EVIDENCE,
+} from "./intents";
+export {
+  type FreshnessWatermark,
+  findFreshnessWatermark,
+  type LintOptions,
+  lintBundle,
+  resolveLink,
+} from "./lint";
+export {
+  appendLog,
+  type CreateInput,
+  createWorkItem,
+  nextId,
+  setEpic,
+  setPriority,
+  setRank,
+  setStatus,
+  slugify,
+} from "./ops";
+export {
+  buildContextPacket,
+  type CommitRef,
+  type ContextPacket,
+  type PacketDep,
+  type PacketLink,
+} from "./packet";
+export {
+  type Concept,
+  type Decision,
+  type Diagnostic,
+  type GenericConcept,
+  isReserved,
+  type Link,
+  parseConcept,
+  type WorkItem,
+} from "./parse";
+export {
+  type IntentDiscoveryDiagnostic,
+  type IntentDiscoveryDiagnosticCode,
+  PROMPT_ROUTING_FIXTURES,
+  type PromptRoutingDiagnostic,
+  type PromptRoutingDiagnosticCode,
+  type PromptRoutingFixture,
+  type PromptRoutingTrait,
+  validateIntentDiscoveryDescriptions,
+  validatePromptRoutingFixtures,
+} from "./prompt-routing";
+export {
+  buildSchemas,
+  type DecisionFrontmatter,
+  type GenericFrontmatter,
+  type Schemas,
+  type WorkItemFrontmatter,
+} from "./schema";
+export { type SearchHit, searchBundle } from "./search";
+export {
+  formatOrigin,
+  type Origin,
+  parseOrigin,
+  recoverOrigin,
+  type ShippedHistory,
+  shippedHistory,
+  shippedWorkflow,
+} from "./shipped";
+export {
+  type LegacyStateOfPlayNote,
+  parseStateOfPlay,
+  presentStateOfPlay,
+  REENTRY_CONTEXT_FORMAT,
+  REENTRY_CONTEXT_V1_FORMAT,
+  type ReentryAssessment,
+  type ReentryContextNote,
+  type ReentryV1ContextNote,
+  STATE_OF_PLAY_PATH,
+  STATE_OF_PLAY_REVIEW_MAX_DAYS,
+  STATE_OF_PLAY_STALE_COMMITS,
+  type StateOfPlayNote,
+  type StateOfPlayParseResult,
+  type StateOfPlayPresentationOptions,
+  type StateOfPlayReview,
+  type StateOfPlayReviewReason,
+  type StateOfPlayView,
+} from "./state-of-play";
+export {
+  byManualOrder,
+  canTransition,
+  DECISION_STATES,
+  type DecisionStatus,
+  isPriority,
+  isReady,
+  isStatus,
+  isTerminalStatus,
+  PRIORITIES,
+  type Priority,
+  STATES,
+  type Status,
+  TERMINAL_STATES,
+  TRANSITIONS,
+  WORK_ITEM_TYPES,
+  type WorkItemType,
+} from "./states";
+export {
+  type Merge3,
+  markerVersion,
+  type UpgradeAction,
+  type UpgradeResult,
+  upgradeAdapter,
+  upgradeWorkflowFile,
+} from "./upgrade";
+export {
+  resolveVerifyMarkers,
+  scanVerifyMarkers,
+  VERIFY_TOKEN,
+  type VerifyMarker,
+  type VerifySource,
+  type VerifyStatusRow,
+  verifyStatus,
+} from "./verify";
+export { DOCKET_VERSION } from "./version";
+export {
+  ADAPTER_MARKER,
+  composeManagedSection,
+  DOCKET_WORKFLOWS,
+  hasAdapterMarker,
+  hasDocketSection,
+  renderAgentSkillStub,
+  renderClaudeSkillStub,
+  renderDocketSection,
+  renderWorkflow,
+  validateWorkflowSemantics,
+  WORKFLOWS_DIR,
+  type WorkflowDef,
+  type WorkflowSemantic,
+  type WorkflowSemanticDiagnostic,
+  workflowPath,
+} from "./workflows";

package/src/indexmd.ts

@@ -0,0 +1,146 @@
+// Generated index.md: derived content is never hand-maintained.
+// Everything above the marker is human preamble and survives regeneration;
+// everything below is machine-owned and rendered deterministically from the
+// bundle (lockfile pattern — committed, and CI fails on drift).
+
+import type { Bundle } from "./bundle";
+import type { GenericConcept, WorkItem } from "./parse";
+import { isTerminalStatus } from "./states";
+
+export const INDEX_MARKER = "<!-- docket:generated -->";
+
+const idNum = (id: string): number => Number(id.match(/(\d+)$/)?.[1] ?? 0);
+const byId = (a: { fm: { id: string } }, b: { fm: { id: string } }): number =>
+  idNum(a.fm.id) - idNum(b.fm.id);
+
+const link = (text: string, path: string): string => `[${text}](/${path})`;
+
+const taskLine = (t: WorkItem, ready: ReadonlySet<string>): string => {
+  const text = link(`${t.fm.id} — ${t.fm.title ?? t.fm.id}`, t.path);
+  if (t.fm.status === "done") return `- ✅ ${text}`;
+  if (t.fm.status === "closed") return `- ⏹️ ${text} *(closed)*`;
+  if (t.fm.status === "in-progress" || t.fm.status === "in-review")
+    return `- 🔄 ${text}`;
+  if (t.fm.status === "blocked") return `- 🚫 ${text}`;
+  return ready.has(t.fm.id) ? `- ${text} *(ready)*` : `- ${text}`;
+};
+
+const tsOf = (t: WorkItem): string =>
+  typeof t.fm.timestamp === "string" ? t.fm.timestamp : "";
+
+/**
+ * Liveness order: what's moving, then what could move, then the
+ * queue, then terminal history newest-first (timestamp is the transition time; ISO
+ * strings compare chronologically). File-derived and deterministic: no
+ * wall-clock input, so regeneration without a bundle change never diffs.
+ */
+export function byLiveness(
+  ready: ReadonlySet<string>,
+): (a: WorkItem, b: WorkItem) => number {
+  const rank = (t: WorkItem): number => {
+    if (t.fm.status === "in-progress" || t.fm.status === "in-review") return 0;
+    if (ready.has(t.fm.id)) return 1;
+    if (isTerminalStatus(t.fm.status)) return 3;
+    return 2; // todo (unready) + blocked
+  };
+  return (a, b) => {
+    const byRank = rank(a) - rank(b);
+    if (byRank !== 0) return byRank;
+    if (rank(a) === 3) {
+      const byClose = tsOf(b).localeCompare(tsOf(a));
+      if (byClose !== 0) return byClose;
+    }
+    return byId(a, b);
+  };
+}
+
+/** The machine-owned body: generic concepts by directory, decisions, work by epic. */
+export function renderIndex(bundle: Bundle): string {
+  const sections: string[] = [];
+
+  const groups = new Map<string, GenericConcept[]>();
+  for (const c of bundle.concepts) {
+    if (c.kind !== "generic") continue;
+    const dir = c.path.includes("/") ? (c.path.split("/")[0] ?? "") : "";
+    const group = groups.get(dir) ?? [];
+    group.push(c);
+    groups.set(dir, group);
+  }
+  for (const [dir, items] of [...groups.entries()].sort()) {
+    const name = dir ? dir[0]?.toUpperCase() + dir.slice(1) : "Concepts";
+    const lines = items
+      .sort((a, z) => a.path.localeCompare(z.path))
+      .map(
+        (c) =>
+          `- ${link(c.fm.title ?? c.path, c.path)}${c.fm.description ? ` — ${c.fm.description}` : ""}`,
+      );
+    sections.push(`## ${name}\n\n${lines.join("\n")}`);
+  }
+
+  if (bundle.decisions.length > 0) {
+    const lines = [...bundle.decisions].sort(byId).map((d) => {
+      const text = link(`${d.fm.id} — ${d.fm.title ?? d.fm.id}`, d.path);
+      return d.fm.status === "superseded"
+        ? `- ~~${text}~~ *(superseded)*`
+        : `- ${text}`;
+    });
+    sections.push(`## Decisions\n\n${lines.join("\n")}`);
+  }
+
+  const ready = new Set(bundle.readyIds());
+  const epics = bundle.workItems.filter((w) => w.fm.type === "Epic").sort(byId);
+  const tasks = bundle.workItems.filter((w) => w.fm.type === "Task").sort(byId);
+  if (epics.length > 0 || tasks.length > 0) {
+    const work: string[] = ["## Work"];
+    const claimed = new Set<string>();
+    const order = byLiveness(ready);
+    for (const epic of epics) {
+      const own = tasks.filter((t) => t.fm.epic?.includes(`/${epic.fm.id}-`));
+      for (const t of own) claimed.add(t.fm.id);
+      // Fully-done epics collapse to their rollup: the history lives
+      // in git and on the epic page; the index is orientation, not archive.
+      const finished =
+        epic.fm.status === "done" &&
+        own.length > 0 &&
+        own.every((t) => t.fm.status === "done");
+      const head = `### ${link(epic.fm.title ?? epic.fm.id, epic.path)} *(${epic.fm.status})*`;
+      if (finished) {
+        work.push(`${head}\n\n✅ all ${own.length} tasks done`);
+        continue;
+      }
+      work.push(head);
+      if (own.length > 0)
+        work.push(
+          own
+            .sort(order)
+            .map((t) => taskLine(t, ready))
+            .join("\n"),
+        );
+    }
+    const orphans = tasks.filter((t) => !claimed.has(t.fm.id));
+    if (orphans.length > 0) {
+      work.push("### No epic");
+      work.push(
+        orphans
+          .sort(order)
+          .map((t) => taskLine(t, ready))
+          .join("\n"),
+      );
+    }
+    sections.push(work.join("\n\n"));
+  }
+
+  return sections.join("\n\n");
+}
+
+/** Splice the generated body below the marker, preserving the human preamble above it. */
+export function applyIndex(current: string, body: string): string {
+  const at = current.indexOf(INDEX_MARKER);
+  const preamble =
+    at >= 0
+      ? current.slice(0, at)
+      : current.trim()
+        ? `${current.trimEnd()}\n\n`
+        : "# Index\n\n";
+  return `${preamble}${INDEX_MARKER}\n\n${body}\n`;
+}