@opum-ai/lore 0.1.0 → 0.2.0

package/src/commands/codex-bridge.ts

@@ -1,49 +0,0 @@
-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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,292 +0,0 @@
-/**
- * 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

@@ -1,89 +0,0 @@
-/**
- * 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);
-}