issue-flow 0.5.2 → 0.7.0

package/dist/chunk-HS4QWZAO.js

@@ -0,0 +1,707 @@
+#!/usr/bin/env node
+import {
+  getProjectRoot,
+  loadIssuesConfig,
+  run
+} from "./chunk-OVFYJLOH.js";
+import {
+  isoNow,
+  issueMetadataSchema,
+  printError,
+  printInfo,
+  printWarning,
+  writeFileAtomic
+} from "./chunk-2Y3UO7H2.js";
+
+// src/issues/registry.ts
+var providers = /* @__PURE__ */ new Map();
+function registerProvider(provider) {
+  providers.set(provider.name, provider);
+}
+function getRegisteredSources() {
+  return [...providers.keys()];
+}
+function getProvider(source) {
+  const provider = providers.get(source);
+  if (provider === void 0) {
+    const available = getRegisteredSources();
+    const hint = available.length > 0 ? `Available sources: ${available.join(", ")}.` : "No Issue providers are registered.";
+    throw new Error(`Unknown Issue source: '${source}'. ${hint}`);
+  }
+  return provider;
+}
+
+// src/issues/hash.ts
+import { createHash } from "crypto";
+function normalizeText(value) {
+  return value.replace(/\r\n?/g, "\n").trim();
+}
+function hashIssueContent(title, body) {
+  const payload = JSON.stringify({
+    title: normalizeText(title),
+    body: normalizeText(body)
+  });
+  const digest = createHash("sha256").update(payload, "utf8").digest("hex");
+  return `sha256:${digest}`;
+}
+
+// src/issues/providers/github.ts
+var VIEW_FIELDS = "number,title,body,labels,state,url,createdAt,updatedAt";
+var PROBE_TIMEOUT_MS = 1e4;
+var NOT_FOUND_PATTERN = /could not resolve to an issue|no issues? found|issue not found|could not find any issue/i;
+function normalizeState(state) {
+  return String(state ?? "").toUpperCase() === "CLOSED" ? "closed" : "open";
+}
+function normalizeLabels(labels) {
+  if (!Array.isArray(labels)) return [];
+  return labels.map((label) => typeof label === "string" ? label : label?.name).filter((name) => typeof name === "string" && name.length > 0);
+}
+function toIssue(payload) {
+  const title = typeof payload.title === "string" ? payload.title : "";
+  const body = typeof payload.body === "string" ? payload.body : "";
+  const number = typeof payload.number === "number" ? payload.number : null;
+  const url = typeof payload.url === "string" && payload.url.length > 0 ? payload.url : null;
+  return {
+    id: number === null ? "" : String(number),
+    number,
+    title,
+    body,
+    labels: normalizeLabels(payload.labels),
+    state: normalizeState(payload.state),
+    source: "github",
+    remoteRef: url,
+    createdAt: typeof payload.createdAt === "string" ? payload.createdAt : "",
+    updatedAt: typeof payload.updatedAt === "string" ? payload.updatedAt : "",
+    contentHash: hashIssueContent(title, body),
+    raw: payload
+  };
+}
+function normalizeId(id) {
+  return id.trim().replace(/^#/, "");
+}
+function extractIssueNumber(output) {
+  return output.match(/\/issues\/(\d+)/)?.[1] ?? null;
+}
+var GitHubIssueProvider = class {
+  name = "github";
+  /** True when gh is installed and authenticated. Never throws. */
+  async isAvailable() {
+    try {
+      const version = await run("gh", ["--version"], { timeout: PROBE_TIMEOUT_MS });
+      if (version.exitCode !== 0) return false;
+      const auth = await run("gh", ["auth", "status"], { timeout: PROBE_TIMEOUT_MS });
+      return auth.exitCode === 0;
+    } catch {
+      return false;
+    }
+  }
+  async get(id) {
+    const issueId = normalizeId(id);
+    const result = await run("gh", ["issue", "view", issueId, "--json", VIEW_FIELDS]);
+    if (result.exitCode !== 0) {
+      const detail = (result.stderr || result.stdout).trim();
+      if (NOT_FOUND_PATTERN.test(detail)) return null;
+      throw new Error(
+        `Failed to fetch GitHub issue #${issueId}: ${detail || "gh issue view failed"}`
+      );
+    }
+    let payload;
+    try {
+      payload = JSON.parse(result.stdout);
+    } catch {
+      throw new Error(
+        `Failed to parse gh output for issue #${issueId}: ${result.stdout.slice(0, 200)}`
+      );
+    }
+    return toIssue(payload);
+  }
+  async create(draft) {
+    const args = ["issue", "create", "--title", draft.title, "--body", draft.body];
+    for (const label of draft.labels) {
+      args.push("--label", label);
+    }
+    const result = await run("gh", args);
+    if (result.exitCode !== 0) {
+      const detail = (result.stderr || result.stdout).trim();
+      throw new Error(`Failed to create GitHub issue: ${detail || "gh issue create failed"}`);
+    }
+    const number = extractIssueNumber(result.stdout);
+    if (!number) {
+      throw new Error(
+        `GitHub issue creation did not report an issue URL: ${result.stdout.trim() || "(no output)"}`
+      );
+    }
+    const created = await this.get(number);
+    if (!created) {
+      throw new Error(`GitHub issue #${number} was created but could not be read back`);
+    }
+    return created;
+  }
+  async close(id) {
+    const issueId = normalizeId(id);
+    const result = await run("gh", ["issue", "close", issueId]);
+    if (result.exitCode !== 0) {
+      const detail = (result.stderr || result.stdout).trim();
+      throw new Error(
+        `Failed to close GitHub issue #${issueId}: ${detail || "gh issue close failed"}`
+      );
+    }
+  }
+};
+var githubIssueProvider = new GitHubIssueProvider();
+
+// src/issues/providers/local.ts
+import { constants } from "fs";
+import { access, mkdir, readdir, readFile, stat, writeFile } from "fs/promises";
+import { join } from "path";
+import { ZodError } from "zod";
+var ISSUES_DIR = "issues";
+var REMOTE_PROBE_TIMEOUT_MS = 1e4;
+function isNotFound(err) {
+  const code = err.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+function normalizeId2(id) {
+  const normalized = id.trim().replace(/^#/, "");
+  if (normalized.length === 0) {
+    throw new Error("Local issue identifier cannot be empty");
+  }
+  if (/[/\\]/.test(normalized) || normalized === "." || normalized === "..") {
+    throw new Error(`Invalid local issue identifier: '${id}'`);
+  }
+  return normalized;
+}
+function toNumber(id) {
+  return /^\d+$/.test(id) ? Number.parseInt(id, 10) : null;
+}
+function parseIssueMarkdown(content) {
+  const lines = content.replace(/\r\n?/g, "\n").split("\n");
+  const headingIndex = lines.findIndex((line) => line.trim().length > 0);
+  const heading = headingIndex === -1 ? void 0 : lines[headingIndex].match(/^#[ \t]+(.*)$/);
+  if (!heading) {
+    return { title: "", body: lines.join("\n").trim() };
+  }
+  return {
+    title: heading[1].trim(),
+    body: lines.slice(headingIndex + 1).join("\n").trim()
+  };
+}
+function renderIssueMarkdown(title, body) {
+  return `# ${title}
+
+${body.trim()}
+`;
+}
+var LocalFileIssueProvider = class {
+  name = "local";
+  configuredRoot;
+  cachedRoot;
+  constructor(projectRoot) {
+    this.configuredRoot = projectRoot;
+  }
+  /** True whenever the project directory exists and is writable. Never throws. */
+  async isAvailable() {
+    try {
+      await access(await this.root(), constants.W_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async get(id) {
+    const issueId = normalizeId2(id);
+    const markdownPath = await this.issueFile(issueId);
+    let raw;
+    try {
+      raw = await readFile(markdownPath, "utf-8");
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+    const { title: headingTitle, body } = parseIssueMarkdown(raw);
+    const metadata = await this.readMetadata(issueId);
+    const title = headingTitle || metadata?.title || "";
+    if (metadata) {
+      return {
+        id: metadata.id,
+        number: metadata.number,
+        title,
+        body,
+        labels: metadata.labels,
+        state: metadata.state,
+        source: "local",
+        remoteRef: metadata.remote?.ref ?? null,
+        createdAt: metadata.createdAt,
+        updatedAt: metadata.updatedAt,
+        contentHash: hashIssueContent(title, body),
+        raw: metadata
+      };
+    }
+    const stats = await stat(markdownPath);
+    return {
+      id: issueId,
+      number: toNumber(issueId),
+      title,
+      body,
+      labels: [],
+      state: "open",
+      source: "local",
+      remoteRef: null,
+      createdAt: stats.birthtime.toISOString(),
+      updatedAt: stats.mtime.toISOString(),
+      contentHash: hashIssueContent(title, body)
+    };
+  }
+  async create(draft) {
+    const id = draft.id === void 0 ? String(await this.allocateNumber()) : normalizeId2(draft.id);
+    const dir = await this.issueDir(id);
+    await mkdir(dir, { recursive: true });
+    try {
+      await writeFile(join(dir, "issue.md"), renderIssueMarkdown(draft.title, draft.body), {
+        encoding: "utf-8",
+        flag: "wx"
+      });
+    } catch (err) {
+      if (err.code === "EEXIST") {
+        throw new Error(
+          `Local issue '${id}' already exists at ${join(ISSUES_DIR, id, "issue.md")}. Remove it or pick another identifier before creating a new Issue.`
+        );
+      }
+      throw err;
+    }
+    const timestamp = isoNow();
+    const metadata = {
+      schemaVersion: 1,
+      id,
+      number: toNumber(id),
+      source: "local",
+      title: draft.title,
+      labels: draft.labels,
+      state: "open",
+      createdAt: timestamp,
+      updatedAt: timestamp,
+      contentHash: hashIssueContent(draft.title, draft.body),
+      ...draft.remote ? { remote: draft.remote } : {}
+    };
+    await this.writeMetadata(id, metadata);
+    return {
+      id,
+      number: metadata.number,
+      title: draft.title,
+      body: draft.body.trim(),
+      labels: draft.labels,
+      state: "open",
+      source: "local",
+      remoteRef: draft.remote?.ref ?? null,
+      createdAt: timestamp,
+      updatedAt: timestamp,
+      contentHash: metadata.contentHash,
+      raw: metadata
+    };
+  }
+  async close(id) {
+    const issue = await this.get(id);
+    if (!issue) {
+      throw new Error(`Local issue '${normalizeId2(id)}' not found under ${ISSUES_DIR}/`);
+    }
+    const issueId = normalizeId2(id);
+    const existing = await this.readMetadata(issueId);
+    await this.writeMetadata(issueId, {
+      schemaVersion: 1,
+      id: issue.id,
+      number: issue.number,
+      source: existing?.source ?? "local",
+      title: issue.title,
+      labels: issue.labels,
+      state: "closed",
+      createdAt: issue.createdAt,
+      updatedAt: isoNow(),
+      contentHash: issue.contentHash,
+      ...existing?.remote ? { remote: existing.remote } : {}
+    });
+  }
+  /**
+   * Next free identifier: above every local number and, when GitHub answers,
+   * above every remote one too. Sharing a numbering space with the remote is
+   * what makes a naive `localMax + 1` collide the moment someone opens an Issue
+   * on GitHub.
+   */
+  async allocateNumber() {
+    const [local, remote] = await Promise.all([this.highestLocalNumber(), highestRemoteNumber()]);
+    return Math.max(local, remote) + 1;
+  }
+  async root() {
+    if (this.configuredRoot !== void 0) return this.configuredRoot;
+    this.cachedRoot ??= await getProjectRoot();
+    return this.cachedRoot;
+  }
+  async issueDir(id) {
+    return join(await this.root(), ISSUES_DIR, id);
+  }
+  async issueFile(id) {
+    return join(await this.issueDir(id), "issue.md");
+  }
+  async metadataFile(id) {
+    return join(await this.issueDir(id), "metadata.json");
+  }
+  /** Parsed metadata.json, or `null` when the file is absent. */
+  async readMetadata(id) {
+    const path = await this.metadataFile(id);
+    const relative = join(ISSUES_DIR, id, "metadata.json");
+    let raw;
+    try {
+      raw = await readFile(path, "utf-8");
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`Invalid JSON in ${relative}: ${err.message}`);
+    }
+    try {
+      return issueMetadataSchema.parse(parsed);
+    } catch (err) {
+      if (err instanceof ZodError) {
+        const details = err.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+        throw new Error(`Invalid issue metadata at ${relative}:
+${details}`);
+      }
+      throw err;
+    }
+  }
+  async writeMetadata(id, metadata) {
+    await writeFileAtomic(await this.metadataFile(id), `${JSON.stringify(metadata, null, 2)}
+`);
+  }
+  /** Highest number across every issues/<id>/metadata.json and numeric directory name. */
+  async highestLocalNumber() {
+    const dir = join(await this.root(), ISSUES_DIR);
+    let entries;
+    try {
+      entries = (await readdir(dir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    } catch (err) {
+      if (isNotFound(err)) return 0;
+      throw err;
+    }
+    const numbers = await Promise.all(
+      entries.map(async (name) => {
+        const fromName = toNumber(name) ?? 0;
+        const fromMetadata = await this.readMetadata(name).then((metadata) => metadata?.number ?? 0).catch(() => 0);
+        return Math.max(fromName, fromMetadata);
+      })
+    );
+    return numbers.reduce((max, value) => Math.max(max, value), 0);
+  }
+};
+var REMOTE_PROBE_SAMPLE_SIZE = 20;
+async function highestRemoteNumber() {
+  const probes = [
+    ["issue", "list"],
+    ["pr", "list"]
+  ];
+  const results = await Promise.all(
+    probes.map(async (args) => {
+      try {
+        const result = await run(
+          "gh",
+          [
+            ...args,
+            "--state",
+            "all",
+            "--limit",
+            String(REMOTE_PROBE_SAMPLE_SIZE),
+            "--json",
+            "number"
+          ],
+          { timeout: REMOTE_PROBE_TIMEOUT_MS }
+        );
+        if (result.exitCode !== 0) return 0;
+        const parsed = JSON.parse(result.stdout);
+        if (!Array.isArray(parsed)) return 0;
+        return parsed.reduce((max, entry) => {
+          const n = entry?.number;
+          return typeof n === "number" ? Math.max(max, n) : max;
+        }, 0);
+      } catch {
+        return 0;
+      }
+    })
+  );
+  return results.reduce((max, value) => Math.max(max, value), 0);
+}
+var localFileIssueProvider = new LocalFileIssueProvider();
+
+// src/issues/bootstrap.ts
+function ensureProvidersRegistered() {
+  const registered = new Set(getRegisteredSources());
+  if (!registered.has("github")) {
+    registerProvider(githubIssueProvider);
+  }
+  if (!registered.has("local")) {
+    registerProvider(localFileIssueProvider);
+  }
+}
+
+// src/issues/resolver.ts
+import { createInterface } from "readline";
+var IssueResolutionError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "IssueResolutionError";
+    this.exitCode = exitCode;
+  }
+};
+var MAX_PROMPT_ATTEMPTS = 3;
+var SOURCE_LABELS = {
+  github: "GitHub",
+  local: "local"
+};
+function sourceLabel(source) {
+  return SOURCE_LABELS[source] ?? source;
+}
+function promptLabel(source) {
+  const label = sourceLabel(source);
+  return label.charAt(0).toUpperCase() + label.slice(1);
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function fetchCandidate(source, id, warn) {
+  let provider;
+  try {
+    provider = getProvider(source);
+  } catch (err) {
+    return { source, issue: null, reason: errorMessage(err) };
+  }
+  let available;
+  try {
+    available = await provider.isAvailable();
+  } catch (err) {
+    return { source, issue: null, reason: `provider unavailable (${errorMessage(err)})` };
+  }
+  if (!available) {
+    return { source, issue: null, reason: "provider unavailable" };
+  }
+  try {
+    const issue = await provider.get(id);
+    return { source, issue, reason: issue === null ? "not found" : null };
+  } catch (err) {
+    const reason = errorMessage(err);
+    warn(`Could not read issue '${id}' from ${sourceLabel(source)}: ${reason}`);
+    return { source, issue: null, reason };
+  }
+}
+function shortHash(hash) {
+  const hex = hash.startsWith("sha256:") ? hash.slice("sha256:".length) : hash;
+  return hex.slice(0, 12);
+}
+function describeCandidate(source, issue) {
+  const lines = issue.body.length === 0 ? 0 : issue.body.split("\n").length;
+  return `  ${sourceLabel(source).padEnd(6)} title: "${issue.title}" | body: ${lines} line(s), ${issue.body.length} char(s) | updated: ${issue.updatedAt} | hash: ${shortHash(issue.contentHash)}`;
+}
+function listSources(candidates) {
+  const labels = candidates.map((candidate) => sourceLabel(candidate.source));
+  if (labels.length <= 1) {
+    return labels.join("");
+  }
+  return `${labels.slice(0, -1).join(", ")} and ${labels[labels.length - 1]}`;
+}
+function createLineReader(rl, output) {
+  const queued = [];
+  let pending = null;
+  let closed = false;
+  rl.on("line", (line) => {
+    if (pending !== null) {
+      const resolve = pending;
+      pending = null;
+      resolve(line);
+      return;
+    }
+    queued.push(line);
+  });
+  rl.on("close", () => {
+    closed = true;
+    if (pending !== null) {
+      const resolve = pending;
+      pending = null;
+      resolve(null);
+    }
+  });
+  return (query) => new Promise((resolve) => {
+    const buffered = queued.shift();
+    if (buffered !== void 0) {
+      resolve(buffered);
+      return;
+    }
+    if (closed) {
+      resolve(null);
+      return;
+    }
+    output.write(query);
+    pending = resolve;
+  });
+}
+async function promptChoice(sources, stdin, stdout, warn) {
+  const options = sources.map((source, index) => `[${index + 1}] ${promptLabel(source)}`);
+  const cancelOption = sources.length + 1;
+  const query = `Which version should be used? ${options.join("  ")}  [${cancelOption}] Cancel: `;
+  const numbers = Array.from({ length: cancelOption }, (_, index) => String(index + 1));
+  const accepted = `${numbers.slice(0, -1).join(", ")} or ${numbers[numbers.length - 1]}`;
+  const rl = createInterface({ input: stdin, output: stdout });
+  const ask = createLineReader(rl, stdout);
+  try {
+    for (let attempt = 0; attempt < MAX_PROMPT_ATTEMPTS; attempt++) {
+      const answer = await ask(query);
+      if (answer === null) {
+        return "cancel";
+      }
+      const choice = answer.trim();
+      const picked = sources[Number(choice) - 1];
+      if (choice.length > 0 && picked !== void 0) {
+        return picked;
+      }
+      if (choice === String(cancelOption)) {
+        return "cancel";
+      }
+      warn(`Invalid choice: '${choice}'. Enter ${accepted}.`);
+    }
+    return "cancel";
+  } finally {
+    rl.close();
+  }
+}
+function isInteractiveByDefault() {
+  const ci = process.env.CI;
+  const inCi = ci !== void 0 && ci !== "" && ci !== "0" && ci.toLowerCase() !== "false";
+  return Boolean(process.stdin.isTTY) && !inCi;
+}
+function buildResolved(issue, source, local, github, divergent) {
+  return { issue, source, local, github, divergent };
+}
+function policyTarget(policy) {
+  if (policy === "prefer-local") {
+    return "local";
+  }
+  if (policy === "prefer-github") {
+    return "github";
+  }
+  return null;
+}
+async function resolveIssue(id, opts = {}) {
+  const info = opts.info ?? printInfo;
+  const warn = opts.warn ?? printWarning;
+  const config = opts.config ?? await loadIssuesConfig({ warn });
+  ensureProvidersRegistered();
+  const sources = opts.sources ?? getRegisteredSources();
+  const candidates = await Promise.all(
+    sources.map((source) => fetchCandidate(source, id, warn))
+  );
+  const issueOf = (source) => candidates.find((candidate) => candidate.source === source)?.issue ?? null;
+  const local = issueOf("local");
+  const github = issueOf("github");
+  const found = candidates.filter(
+    (candidate) => candidate.issue !== null
+  );
+  if (found.length === 0) {
+    const details = candidates.map((candidate) => `${sourceLabel(candidate.source)}: ${candidate.reason ?? "not found"}`).join("; ");
+    const where = details.length > 0 ? ` (${details})` : "";
+    throw new IssueResolutionError(`Issue '${id}' not found in any registered origin${where}`);
+  }
+  const build = (candidate, divergent) => buildResolved(candidate.issue, candidate.source, local, github, divergent);
+  const firstFound = found[0];
+  if (found.length === 1) {
+    return build(firstFound, false);
+  }
+  const preferred = found.find((candidate) => candidate.source === config.preferredProvider) ?? firstFound;
+  const distinct = new Set(found.map((candidate) => candidate.issue.contentHash));
+  if (distinct.size === 1) {
+    info(
+      `Issue '${id}' has identical content in ${listSources(found)}; using ${sourceLabel(preferred.source)}.`
+    );
+    return build(preferred, false);
+  }
+  info(`Issue '${id}' differs between origins:`);
+  for (const candidate of found) {
+    info(describeCandidate(candidate.source, candidate.issue));
+  }
+  const target = policyTarget(config.conflictPolicy);
+  if (target !== null) {
+    const chosen = found.find((candidate) => candidate.source === target);
+    if (chosen !== void 0) {
+      info(`Conflict policy '${config.conflictPolicy}': using the ${sourceLabel(target)} version.`);
+      return build(chosen, true);
+    }
+    warn(
+      `Conflict policy '${config.conflictPolicy}' does not apply to Issue '${id}' (${sourceLabel(target)} has no version of it); using ${sourceLabel(preferred.source)}.`
+    );
+    return build(preferred, true);
+  }
+  const interactive = opts.interactive ?? isInteractiveByDefault();
+  if (!interactive) {
+    warn(
+      `Divergent Issue '${id}' and conflict policy 'ask' in a non-interactive environment; using the preferred provider (${sourceLabel(preferred.source)}).`
+    );
+    return build(preferred, true);
+  }
+  const choice = await promptChoice(
+    found.map((candidate) => candidate.source),
+    opts.stdin ?? process.stdin,
+    opts.stdout ?? process.stdout,
+    warn
+  );
+  if (choice === "cancel") {
+    throw new IssueResolutionError(
+      `Cancelled: Issue '${id}' diverges between ${listSources(found)}.`
+    );
+  }
+  const picked = found.find((candidate) => candidate.source === choice);
+  return build(picked, true);
+}
+
+// src/issues/context.ts
+function localIssueRef(id) {
+  return `issues/${id}/issue.md`;
+}
+function issueReference(issue) {
+  return issue.remoteRef ?? localIssueRef(issue.id);
+}
+var NO_LABELS = "(none)";
+function issuePlaceholders(resolved) {
+  const { issue } = resolved;
+  return {
+    __ISSUE_TITLE__: issue.title,
+    __ISSUE_BODY__: issue.body,
+    __ISSUE_LABELS__: issue.labels.length > 0 ? issue.labels.join(", ") : NO_LABELS,
+    __ISSUE_SOURCE__: resolved.source,
+    __ISSUE_URL__: issueReference(issue)
+  };
+}
+async function resolveCommandIssue(id, preResolved, options) {
+  if (preResolved !== void 0) {
+    return { ok: true, resolved: preResolved };
+  }
+  try {
+    return { ok: true, resolved: await resolveIssue(id, options) };
+  } catch (err) {
+    if (err instanceof IssueResolutionError) {
+      printError(err.message);
+      return { ok: false, code: err.exitCode };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    printError(`Could not resolve issue '${id}': ${message}`);
+    return { ok: false, code: 1 };
+  }
+}
+
+export {
+  getProvider,
+  ensureProvidersRegistered,
+  localIssueRef,
+  issuePlaceholders,
+  resolveCommandIssue
+};
+//# sourceMappingURL=chunk-HS4QWZAO.js.map