@opum-ai/lore 0.1.0

package/src/commands/codex-bridge.ts

@@ -0,0 +1,49 @@
+import { dirname, join } from "node:path";
+import type { BridgeAction } from "../core/agent-bridge";
+import { AGENTS_MD_REL_PATH, CODEX_SKILL_REL_PATH, planCodexBridge } from "../core/codex-bridge";
+import { readFileIfPresent } from "../errors";
+import { assertNoSymlinkInAnyPath, ensureDir, writeFileAtomic } from "./fswrite";
+
+export interface CodexBridgeResult {
+  root: string;
+  files: ReadonlyArray<{ path: string; action: BridgeAction }>;
+}
+
+export function applyCodexBridge(options: { root: string; force: boolean; check: boolean }): CodexBridgeResult {
+  const skillRaw = readFileIfPresent(join(options.root, CODEX_SKILL_REL_PATH), CODEX_SKILL_REL_PATH);
+  const agentsRaw = readFileIfPresent(join(options.root, AGENTS_MD_REL_PATH), AGENTS_MD_REL_PATH);
+  const skillOnDisk = normalize(skillRaw);
+  const agentsOnDisk = normalize(agentsRaw);
+  const agentsStyle = detectStyle(agentsRaw);
+  const plan = planCodexBridge({ skillOnDisk, agentsOnDisk, force: options.force, check: options.check });
+
+  if (!options.check) {
+    const targets = plan.files.filter((file) => file.contents !== null).map((file) => file.path);
+    assertNoSymlinkInAnyPath(options.root, targets);
+    for (const file of plan.files) {
+      if (file.contents === null) continue;
+      ensureDir(options.root, dirname(file.path));
+      const contents = file.path === AGENTS_MD_REL_PATH ? restyle(file.contents, agentsStyle) : file.contents;
+      writeFileAtomic(join(options.root, file.path), contents, file.path);
+    }
+  }
+
+  return { root: options.root, files: plan.files.map(({ path, action }) => ({ path, action })) };
+}
+
+function normalize(raw: string | undefined): string | null {
+  return raw === undefined ? null : raw.replace(/^\uFEFF+/, "").replace(/\r\n?/g, "\n");
+}
+
+function detectStyle(raw: string | undefined): { bom: boolean; eol: "\n" | "\r\n" | "\r" } {
+  if (raw === undefined) return { bom: false, eol: "\n" };
+  return {
+    bom: raw.startsWith("\uFEFF"),
+    eol: raw.includes("\r\n") ? "\r\n" : raw.includes("\r") ? "\r" : "\n",
+  };
+}
+
+function restyle(contents: string, style: { bom: boolean; eol: "\n" | "\r\n" | "\r" }): string {
+  const withEol = style.eol === "\n" ? contents : contents.replace(/\n/g, style.eol);
+  return style.bom ? `\uFEFF${withEol}` : withEol;
+}

package/src/commands/concurrency.ts

@@ -0,0 +1,48 @@
+/**
+ * commands/concurrency.ts — {@link mapWithConcurrency}, a tiny worker-pool over a shared cursor,
+ * plus {@link TASK_DETAILS_CONCURRENCY}, the shared cap it bounds Backlog `viewTask` fan-out to.
+ *
+ * Pure and dependency-free (no import of any other `commands/` module) so it can be shared by
+ * `commands/link.ts` and `commands/reconcile-shared.ts` without either importing the other:
+ * `reconcile-shared.ts` already imports `verifiedViewTask`/`dedupeTaskIds`/`defaultAdapter` FROM
+ * `link.ts`, so `link.ts` importing anything back from `reconcile-shared.ts` would create a
+ * `link -> reconcile-shared -> link` cycle (LORE-233). Originally lived solely in
+ * `reconcile-shared.ts` (LORE-111, bounding `resolveTaskDetails`'s fan-out and `check.ts`'s
+ * `probeLiveness`); relocated here so `link.ts`'s own up-front task-existence-check fan-out
+ * (`runLink`) could reuse the identical helper and cap instead of duplicating either.
+ * `reconcile-shared.ts` re-exports both so its own existing importers (`check.ts`,
+ * `reconcile-shared.test.ts`) keep working unchanged.
+ */
+
+/**
+ * How many `adapter.viewTask` calls a caller runs at once — bounded so a large task-id fan-out
+ * (a bundle linking many distinct ids, or a multi-id `lore link`) does not spawn one Backlog CLI
+ * subprocess per id fully concurrently (which can exhaust process/file-descriptor limits or
+ * overwhelm the Backlog CLI). Mirrors `check.ts`'s own `LIVENESS_CONCURRENCY` cap on external-URL
+ * liveness probes — same shape of problem (unbounded subprocess/socket fan-out), same fix.
+ * Exported so tests can assert against the real cap rather than duplicating (and risking drift
+ * from) a hardcoded copy.
+ */
+export const TASK_DETAILS_CONCURRENCY = 8;
+
+/**
+ * Run `fn` over `items` with at most `limit` in flight at once — a tiny worker-pool over a shared
+ * cursor. Shared by `reconcile-shared.ts`'s `resolveTaskDetails` (bounding concurrent
+ * `adapter.viewTask` Backlog subprocess spawns), `check.ts`'s `probeLiveness` (bounding concurrent
+ * external-URL fetches), and `link.ts`'s `runLink` (bounding its own up-front `verifiedViewTask`
+ * existence-check fan-out).
+ */
+export async function mapWithConcurrency<T>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T) => Promise<void>,
+): Promise<void> {
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    while (cursor < items.length) {
+      const item = items[cursor++] as T;
+      await fn(item);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}

package/src/commands/context.ts

@@ -0,0 +1,292 @@
+/**
+ * commands/context.ts — `lore context <id> [--max-tokens <n>] [--depth <n>]`.
+ *
+ * The thin, read-only layer that emits a **token-budgeted context pack** for one
+ * concept (cli-surface §context; LORE-34). Commander supplies a verified indexed
+ * {@link BundleGraph} with automatic reference fallback; direct core callers
+ * retain the reference loader. It then hands the target id, neighbor radius
+ * (`--depth`, default {@link DEFAULT_DEPTH}), and budget (`--max-tokens`) to the
+ * pure {@link buildContext} shaper, which gathers the target's neighborhood via
+ * the shared {@link subgraph} traversal and compacts it to the target's full body
+ * plus one-line neighbor summaries.
+ *
+ * Output follows the uniform CLI modes: the `{schemaVersion, kind:
+ * "context.export", data}` envelope under the global `--json`, and otherwise a
+ * pasteable text pack — the target's body followed by the neighbor compaction —
+ * with a §3 truncation footer when the budget dropped neighbors. There is no
+ * command-specific JSON flag; machine consumers use the same `--json` they use
+ * everywhere. The pretty and plain renderers are identical (the pack is structural —
+ * no severities to color), so they share one renderer.
+ *
+ * The positional `<id>` is normalized through {@link idFromPath} exactly as `lore
+ * graph`/`rename`/`supersede` normalize theirs, so a path-form, `./`-prefixed, or
+ * `.md`-suffixed id resolves to the same bundle key.
+ *
+ * Validation lives here (the budget/compaction computation stays pure in
+ * `core/context.ts`): a missing or duplicate `<id>`, an unknown flag, a
+ * repeated/value-less/non-integer/too-large/non-positive `--max-tokens`, or a
+ * repeated/value-less/non-integer/too-large/negative `--depth` is a `usage` error
+ * (exit 2); an `<id>` absent from the bundle surfaces as the `not_found` error
+ * (exit 3) {@link buildContext} throws.
+ */
+
+import { join } from "node:path";
+import type { BacklogAdapter } from "../adapters/backlog";
+import { loadBundle } from "../core/bundle";
+import { idFromPath } from "../core/concept";
+import { buildContext, type ContextExport, DEFAULT_DEPTH } from "../core/context";
+import { loadProfile } from "../core/profile";
+import { loadRetrievalGraph, type RetrievalGraphLoader } from "../core/retrieval";
+import { DOCS_DIR } from "../core/scaffold";
+import { parseQualifiedWorkspaceId, qualifyWorkspaceId } from "../core/workspace-contract";
+import type { WorkspaceRetrievalContext, WorkspaceRetrievalSelection } from "../core/workspace-retrieval";
+import { EXIT_OK, LoreError, WarningCollector, type Writer } from "../errors";
+import { emit, type OutputContext, type Renderable, renderTruncationLine, truncation } from "../output";
+import { parseCommandArgs, singleOptionValue, workspaceSelection } from "./args";
+
+/** Options for {@link runContext}; `root` and the streams are injectable for tests. */
+export interface ContextOptions {
+  /** The repo root the `docs/` bundle resolves against. */
+  root: string;
+  /** The resolved output mode/color (from `output.ts`). */
+  output: OutputContext;
+  /** The command's normalized positional + flag tokens from Commander. */
+  args: readonly string[];
+  /** stdout sink; defaults to `process.stdout`. */
+  stdout?: Writer;
+  /** stderr sink for advisory warnings; defaults to `process.stderr`. */
+  stderr?: Writer;
+  /** Backlog snapshot seam used only by indexed projection freshness/builds. */
+  adapter?: BacklogAdapter;
+  /** Indexed/reference selector injected by the Commander handler or conformance tests. */
+  retrieval?: RetrievalGraphLoader;
+}
+
+/** The parsed form of `lore context`'s arguments. */
+interface ContextArgs {
+  /** The target concept id (positional, already {@link idFromPath}-normalized). */
+  id: string;
+  /** The token budget (`--max-tokens`); `undefined` means no size trim (bounded only by depth). */
+  maxTokens?: number;
+  /** The hop radius (`--depth`); `undefined` falls back to {@link DEFAULT_DEPTH}. */
+  depth?: number;
+  readonly workspace?: WorkspaceRetrievalSelection;
+}
+
+/**
+ * Run `lore context`: parse the arguments, load the bundle, build the context pack,
+ * emit the `context.export`, and return `0`. A bad flag/positional throws a `usage`
+ * {@link LoreError} (exit `2`); an `<id>` not in the bundle a `not_found` one (exit
+ * `3`).
+ */
+export function runContext(options: ContextOptions): number | Promise<number> {
+  const parsed = parseContextArgs(options.args);
+  const advisories = new WarningCollector();
+  const retrieval = options.retrieval ?? (parsed.workspace !== undefined ? loadRetrievalGraph : undefined);
+  if (retrieval !== undefined) {
+    return retrieval({
+      root: options.root,
+      warnings: advisories,
+      adapter: options.adapter,
+      ...(parsed.workspace !== undefined ? { workspace: parsed.workspace } : {}),
+    }).then(async (loaded) => {
+      try {
+        const graph =
+          loaded.indexed === undefined
+            ? loaded.graph
+            : withConceptBody(loaded.graph, parsed.id, await loaded.indexed.readConceptBody(parsed.id));
+        return finishContext(options, parsed, graph, advisories, loaded.workspace);
+      } finally {
+        await loaded.dispose?.();
+      }
+    });
+  }
+  const profile = loadProfile({ root: options.root });
+  const graph = loadBundle(join(options.root, DOCS_DIR), { warnings: advisories, profile });
+  return finishContext(options, parsed, graph, advisories);
+}
+
+function withConceptBody(
+  graph: ReturnType<typeof loadBundle>,
+  id: string,
+  body: string | undefined,
+): ReturnType<typeof loadBundle> {
+  if (body === undefined) return graph;
+  const concept = graph.concepts.get(id);
+  if (concept === undefined) return graph;
+  const concepts = new Map(graph.concepts);
+  concepts.set(id, { ...concept, body });
+  return { ...graph, concepts };
+}
+
+function finishContext(
+  options: ContextOptions,
+  parsed: ContextArgs,
+  graph: ReturnType<typeof loadBundle>,
+  advisories: WarningCollector,
+  workspace?: WorkspaceRetrievalContext,
+): number {
+  // Flush load warnings before buildContext, which throws not_found for an unknown
+  // target — otherwise an advisory explaining *why* a file is not a concept would be
+  // discarded on exactly the path that most needs it (mirrors `lore graph`).
+  advisories.flush({ color: options.output.color, stderr: options.stderr });
+
+  const base = buildContext(graph, parsed.id, { depth: parsed.depth, maxTokens: parsed.maxTokens });
+  const data: ContextExport =
+    workspace === undefined
+      ? base
+      : {
+          ...base,
+          target: { ...base.target, provenance: workspace.provenanceById.get(base.target.id) },
+          neighbors: base.neighbors.map((neighbor) => ({
+            ...neighbor,
+            provenance: workspace.provenanceById.get(neighbor.id),
+          })),
+          workspace: workspace.scope,
+        };
+  emit(contextRenderable(data), options.output, options.stdout);
+  return EXIT_OK;
+}
+
+// ── Argument parsing ───────────────────────────────────────────────────────────
+
+/**
+ * Parse `context`'s tokens into the required `<id>` positional and the value flags
+ * `--max-tokens <n>` / `--depth <n>` (also accepting the `--flag=value` form). The
+ * Commander has already resolved Lore's global flags, so a `--`-prefixed token here is
+ * a command flag: an unrecognized one is a `usage` error, as is a repeated or
+ * value-less value flag, a non-integer/out-of-range value, a missing `<id>`, or a
+ * second positional. A `--` ends option parsing. The `<id>` is
+ * {@link idFromPath}-normalized so path/`.md`/`./` forms resolve.
+ */
+function parseContextArgs(args: readonly string[]): ContextArgs {
+  const parsed = parseCommandArgs(args, "context");
+  const workspace = workspaceSelection(parsed);
+  const positionals = parsed.positionals;
+  const rawMaxTokens = singleOptionValue(parsed, "max-tokens");
+  const rawDepth = singleOptionValue(parsed, "depth");
+  if (rawMaxTokens === "") throw usage("--max-tokens needs a value", "pass a value, e.g. `--max-tokens 2`");
+  if (rawDepth === "") throw usage("--depth needs a value", "pass a value, e.g. `--depth 2`");
+  const maxTokens = rawMaxTokens === undefined ? undefined : parseCount("--max-tokens", rawMaxTokens, { min: 1 });
+  const depth = rawDepth === undefined ? undefined : parseCount("--depth", rawDepth, { min: 0 });
+  if (positionals.length === 0) {
+    throw usage(
+      "`lore context` needs a concept id",
+      "give the concept to build context for, e.g. `lore context stories/x`",
+    );
+  }
+  if (positionals.length > 1) {
+    throw usage(`unexpected argument "${positionals[1]}"`, "run `lore context <id> [--max-tokens <n>] [--depth <n>]`");
+  }
+  return {
+    id: normalizeContextId(positionals[0] as string, workspace !== undefined),
+    maxTokens,
+    depth,
+    workspace,
+  };
+}
+
+function normalizeContextId(raw: string, workspace: boolean): string {
+  if (!workspace) return idFromPath(raw);
+  try {
+    const parsed = parseQualifiedWorkspaceId(raw);
+    return qualifyWorkspaceId(parsed.memberId, idFromPath(parsed.sourceId));
+  } catch {
+    throw usage(`invalid workspace concept id "${raw}"`, "use the unambiguous <member-id>::<source-id> form");
+  }
+}
+
+/**
+ * Parse a count flag's value as an integer at or above `min` (`--depth` allows `0`,
+ * `--max-tokens` requires a positive budget). Rejects a non-digit run
+ * (`Number()` would coerce `"1.5"`/`"0x2"`/`" 2 "`/`"1e3"`), a value below `min`,
+ * and a precision-losing `> 2^53` run — mirroring `lore graph`'s `--depth` guard so
+ * the two commands accept counts identically.
+ */
+function parseCount(flag: string, value: string, opts: { min: number }): number {
+  if (!/^\d+$/.test(value)) {
+    throw usage(
+      `invalid ${flag} "${value}"`,
+      `pass an integer ≥ ${opts.min}, e.g. \`${flag} ${opts.min + 1}\`; ${flag} needs a value before a separate flag-looking token`,
+    );
+  }
+  const count = Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(count)) {
+    throw usage(`${flag} "${value}" is too large`, "pass a smaller integer");
+  }
+  if (count < opts.min) {
+    throw usage(`invalid ${flag} "${value}"`, `pass an integer ≥ ${opts.min}, e.g. \`${flag} ${opts.min + 1}\``);
+  }
+  return count;
+}
+
+/**
+ * Read a value flag's argument: its inline `--flag=value` form when present, else
+ * the **next** token. A missing/empty value — or a next token that is itself an
+ * option (`--depth --max-tokens`) — is a `usage` error rather than a silently
+ * swallowed flag (mirroring `lore graph`'s value-flag guard).
+ */
+// ── Output ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The per-result rendering bundle for `context` (output.ts dispatches on the mode).
+ * `--json` always carries the structured {@link ContextExport}; the pretty/plain
+ * text is the pasteable pack. The two text modes render identically (the data is
+ * structural — no severities to color), so pretty and plain share one renderer.
+ */
+function contextRenderable(data: ContextExport): Renderable<ContextExport> {
+  return { kind: "context.export", data, pretty: renderText, plain: renderText };
+}
+
+/**
+ * A human/pipe-stable context pack: a header naming the target, its depth/budget and
+ * the pack's `~tokens`, then the target's full body, then a `neighbors (<shown> of
+ * <total>)` section with one `- <id>  [<type>]  — <summary>` line each (the `— …`
+ * dropped when a neighbor has no summary), and a trailing budget line: an
+ * over-budget warning when the always-included target alone exceeds `--max-tokens`,
+ * else the §3 truncation footer when the budget dropped neighbors. ANSI-free and
+ * deterministic.
+ */
+function renderText(data: ContextExport): string {
+  const budget = data.maxTokens !== undefined ? `, budget ${data.maxTokens}` : "";
+  const lines = [
+    ...(data.workspace !== undefined
+      ? [`workspace: ${data.workspace.workspaceId} (${data.workspace.repositories.length} repositories)`]
+      : []),
+    `context: ${data.root}  [${data.target.type}] — depth ${data.depth}${budget}, ~${data.tokenEstimate} tokens (chars/4)`,
+    "",
+    data.target.body.replace(/\n+$/, ""),
+    "",
+    `neighbors (${data.shown} of ${data.total}):`,
+  ];
+  for (const neighbor of data.neighbors) {
+    const summary = neighbor.summary !== undefined ? `  — ${neighbor.summary}` : "";
+    lines.push(`  - ${neighbor.id}  [${neighbor.type}]${summary}`);
+  }
+  const footer = budgetFooter(data);
+  if (footer !== "") {
+    lines.push(footer);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The trailing budget line for the pack, or `""` when it fully fit. Over budget (the
+ * mandatory target alone exceeds `--max-tokens`, so no neighbor could be dropped to
+ * help) gets an explicit warning; otherwise a dropped-neighbor count gets the §3
+ * truncation footer. The hint is **only** `raise --max-tokens` — lowering `--depth`
+ * cannot surface more neighbors (the included set is a budget-bound nearest-first
+ * prefix, so a smaller `--depth` only removes farther candidates that were never
+ * going to be included).
+ */
+function budgetFooter(data: ContextExport): string {
+  if (data.maxTokens !== undefined && data.tokenEstimate > data.maxTokens) {
+    return `over budget: ~${data.tokenEstimate} tokens exceeds the ${data.maxTokens}-token limit — the target is always included; raise --max-tokens`;
+  }
+  return renderTruncationLine(truncation(data.total, data.shown, "raise --max-tokens to include more"));
+}
+
+/** A `usage` {@link LoreError} (exit `2`) with an actionable hint. */
+function usage(message: string, hint: string): LoreError {
+  return new LoreError("usage", message, hint);
+}

package/src/commands/discover.ts

@@ -0,0 +1,89 @@
+/**
+ * commands/discover.ts — the shared file-discovery + read seam for the command layer.
+ *
+ * Every command that operates over a set of bundle files — `validate`, `check`, `replace` (and the
+ * `rename`/`supersede` consumers next) — needs the same three primitives: read a file as UTF-8 with
+ * the project's `denied`/`not_found` error classification, derive a stable **canonical identity** for
+ * de-duplication, and render a file's **repo-relative** display path. They lived as near-identical
+ * copies in each command (a `/code-review max` finding); centralizing them here keeps one behavior, so
+ * two commands can't classify a read failure or fold a duplicate path differently. Pairs with
+ * {@link fswrite} (the write seam) — discovery/read here, write there, judgement in `core/`.
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, join, posix, relative, sep } from "node:path";
+import { walkMarkdown } from "../core/bundle";
+import { DOCS_DIR } from "../core/scaffold";
+import { ioError } from "../errors";
+
+/** Read one file as UTF-8, mapping an I/O failure to a classified {@link LoreError} via the shared {@link ioError} policy. */
+export function readSource(abs: string, display: string): string {
+  try {
+    return readFileSync(abs, "utf8");
+  } catch (cause) {
+    ioError(cause, {
+      denied: { message: `permission denied reading ${display}`, hint: `make ${display} readable` },
+      notFound: { message: `cannot read ${display}`, hint: "check the path exists and is readable" },
+      input: { path: display },
+    });
+  }
+}
+
+/** The reserved index file name (mirrors `core/indexes.ts`'s own private constant of the same name). */
+const INDEX_FILE = "index.md";
+
+/**
+ * Read every existing `index.md` under the bundle as `bundle-relative-path → raw bytes` — the
+ * determinism seam `core/indexes.ts`'s `generateIndexes` splices into. Shared by `rename.ts` and
+ * `sync.ts`, both of which regenerate index hubs against whatever is currently on disk.
+ */
+export function readIndexBytes(docsRoot: string): Map<string, string> {
+  const bytes = new Map<string, string>();
+  for (const rel of walkMarkdown(docsRoot, undefined)) {
+    if (posix.basename(rel) === INDEX_FILE) {
+      bytes.set(rel, readSource(join(docsRoot, rel), `${DOCS_DIR}/${rel}`));
+    }
+  }
+  return bytes;
+}
+
+/**
+ * A stable de-duplication key for an absolute file path: its `realpath` when resolvable (which folds
+ * case on a case-insensitive filesystem and collapses symlinks, so two spellings of one physical file
+ * — or a symlink and its target — share a key), else the path verbatim (a file that vanished mid-walk
+ * still gets a key, and {@link readSource} raises the real I/O error).
+ */
+export function canonicalIdentity(abs: string): string {
+  try {
+    return realpathSync.native(abs);
+  } catch {
+    return abs;
+  }
+}
+
+/**
+ * The repo-relative POSIX path for a discovered file, for stable display and de-duplication. A path
+ * inside the repo renders relative (`docs/adr/x.md`); a path **outside** the repo keeps its absolute
+ * form (the relative path would escape with `../`). The `..` escape is matched by path **segment**, so
+ * a real in-repo file whose first segment merely starts with `..` (e.g. `..notes/x.md`) is not pushed
+ * out to its absolute form.
+ */
+export function toRepoRelative(root: string, abs: string): string {
+  const rel = relative(root, abs);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    return abs;
+  }
+  return rel.split(sep).join("/");
+}
+
+/**
+ * Whether `abs` resolves **inside** the repo `root` — the single repo-containment predicate the
+ * commands share, so the bundle-escape decision is made one way everywhere (a `/code-review max`
+ * finding: `validate` and `replace` had drifted on the `..`-segment edge). Matches
+ * {@link toRepoRelative}'s segment rule: a path equal to `..`, beginning `../`, or absolute after
+ * relativizing is outside; anything else is inside.
+ */
+export function withinRepo(root: string, abs: string): boolean {
+  const rel = relative(root, abs);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}