@opum-ai/lore 0.1.0

package/src/commands/args.ts

@@ -0,0 +1,209 @@
+/**
+ * commands/args.ts — the shared Commander-backed command parser.
+ *
+ * Command names and options come from `core/manifest.ts`, the same declaration
+ * source used by the top-level Commander graph and generated help. Thin command
+ * handlers retain only command-specific arity/value/business validation.
+ */
+
+import { posix } from "node:path";
+import { Command, CommanderError, Option } from "commander";
+import { findManifestCommand, type ManifestFlag } from "../core/manifest";
+import { RESERVED_STEMS } from "../core/scaffold";
+import type { WorkspaceRetrievalSelection } from "../core/workspace-retrieval";
+import { LoreError } from "../errors";
+
+/** Commander parse failure enriched by the local subcommand that raised it. */
+interface CommandScopedError extends CommanderError {
+  loreCommand?: string;
+}
+
+/** The parsed form of a command's arguments. */
+export interface ParsedArgs {
+  /** Every non-flag token, in order (everything after a `--` marker included verbatim). */
+  readonly positionals: string[];
+  /** The set of recognized `--flag` names that were passed. */
+  readonly flags: ReadonlySet<string>;
+  /** Every value occurrence for each value-taking flag, in command-line order. */
+  readonly values: ReadonlyMap<string, readonly string[]>;
+  /** Number of times each option occurred, including boolean switches. */
+  readonly counts: ReadonlyMap<string, number>;
+}
+
+/**
+ * Parse one command's tokens with a fresh local Commander instance sourced from
+ * its manifest declaration. A variadic positional captures all operands so each
+ * thin handler can preserve its established arity wording and input metadata.
+ */
+export function parseCommandArgs(args: readonly string[], command: string): ParsedArgs {
+  const definition = findManifestCommand(command);
+  if (definition === undefined) {
+    throw new Error(`missing CLI manifest definition for command "${command}"`);
+  }
+  const flags = new Set<string>();
+  const values = new Map<string, string[]>();
+  const counts = new Map<string, number>();
+  const parser = new Command(command)
+    .helpOption(false)
+    .helpCommand(false)
+    .showSuggestionAfterError(false)
+    .exitOverride()
+    .configureOutput({ writeOut: () => {}, writeErr: () => {} })
+    .argument("[args...]")
+    .action(() => {});
+  for (const flag of definition.flags) {
+    parser.addOption(commanderOption(flag));
+    parser.on(`option:${flag.name}`, (value?: string) => {
+      flags.add(flag.name);
+      counts.set(flag.name, (counts.get(flag.name) ?? 0) + 1);
+      if (value !== undefined) {
+        const collected = values.get(flag.name) ?? [];
+        collected.push(value);
+        values.set(flag.name, collected);
+      }
+    });
+  }
+  try {
+    parser.parse([...args], { from: "user" });
+  } catch (error) {
+    throw commanderUsageError(error, command);
+  }
+  return { positionals: [...parser.args], flags, values, counts };
+}
+
+/** Commander flag declaration sourced from one manifest flag. */
+export function optionSyntax(flag: ManifestFlag): string {
+  const long = `--${flag.name}${flag.takesValue ? " <value>" : ""}`;
+  return flag.alias === undefined ? long : `-${flag.alias}, ${long}`;
+}
+
+/**
+ * Build one Commander option with Lore's compatibility rule for separated
+ * values: a required option must not consume a following long/global flag.
+ * Commander normally accepts such tokens as values; Lore has always reported
+ * the preceding option as value-less instead.
+ */
+export function commanderOption(flag: ManifestFlag): Option {
+  const option = new Option(optionSyntax(flag), flag.summary);
+  if (flag.takesValue) {
+    option.argParser((value) => {
+      if (value.startsWith("--") || value === "-h" || value === "-v") {
+        throw usage(`--${flag.name} needs a value`, `pass a value, e.g. --${flag.name}=<value>`);
+      }
+      return value;
+    });
+  }
+  return option;
+}
+
+/** Extract an unknown command from a Commander failure. */
+export function commanderUnknownCommand(error: unknown): string | undefined {
+  if (!(error instanceof CommanderError) || error.code !== "commander.unknownCommand") {
+    return undefined;
+  }
+  return /unknown command '([^']+)'/.exec(error.message)?.[1];
+}
+
+/** Translate a caught Commander parser failure into Lore's semantic usage error. */
+export function commanderUsageError(error: unknown, command?: string): LoreError {
+  if (!(error instanceof CommanderError)) {
+    throw error;
+  }
+  const scopedCommand = command ?? (error as CommandScopedError).loreCommand;
+  const unknownCommand = commanderUnknownCommand(error);
+  if (unknownCommand !== undefined) {
+    return new LoreError("usage", `unknown command "${unknownCommand}"`, "run `lore --help` to list commands", {
+      command: unknownCommand,
+    });
+  }
+  const unknownOption = /unknown option '([^']+)'/.exec(error.message)?.[1];
+  if (unknownOption !== undefined) {
+    const equals = unknownOption.indexOf("=");
+    if (scopedCommand !== undefined && equals > 0) {
+      const option = unknownOption.slice(0, equals);
+      const name = option.startsWith("--") ? option.slice(2) : option;
+      const declared = findManifestCommand(scopedCommand)?.flags.find((flag) => flag.name === name);
+      if (declared !== undefined && !declared.takesValue) {
+        return usage(`${option} takes no value`, `pass ${option} on its own`);
+      }
+    }
+    const scope = scopedCommand === undefined ? "lore --help" : `lore ${scopedCommand} --help`;
+    return new LoreError("usage", `unknown option "${unknownOption}"`, `run \`${scope}\` to list options`, {
+      options: [unknownOption],
+    });
+  }
+  const missingValue = /option '([^']+)' argument missing/.exec(error.message)?.[1];
+  if (missingValue !== undefined) {
+    const flag = missingValue.split(/[ ,]/, 1)[0] as string;
+    return usage(`${flag} needs a value`, `pass a value, e.g. ${flag}=<value>`);
+  }
+  return usage(
+    error.message.replace(/^error:\s*/, ""),
+    scopedCommand === undefined
+      ? "run `lore --help` to list commands and options"
+      : `run \`lore ${scopedCommand} --help\``,
+  );
+}
+
+/** Return all values for a flag, or an empty array when it was absent. */
+export function optionValues(parsed: ParsedArgs, name: string): readonly string[] {
+  return parsed.values.get(name) ?? [];
+}
+
+/** Return a single flag value, rejecting a duplicate with the established Lore wording. */
+export function singleOptionValue(parsed: ParsedArgs, name: string): string | undefined {
+  const values = optionValues(parsed, name);
+  if (values.length > 1) {
+    throw usage(`--${name} given more than once`, `pass --${name} at most once`);
+  }
+  return values[0];
+}
+
+/** Reject duplicate boolean occurrences for commands whose prior contract did so. */
+export function assertFlagAtMostOnce(parsed: ParsedArgs, name: string): void {
+  if ((parsed.counts.get(name) ?? 0) > 1) {
+    throw usage(`--${name} given more than once`, `pass --${name} at most once`);
+  }
+}
+
+/** Parse the shared explicit workspace/repository selection flags. */
+export function workspaceSelection(parsed: ParsedArgs): WorkspaceRetrievalSelection | undefined {
+  const rawManifest = singleOptionValue(parsed, "workspace");
+  const memberIds = optionValues(parsed, "repository").map((value) => value.trim());
+  if (rawManifest === "" || rawManifest?.trim() === "") {
+    throw usage("--workspace needs a value", "pass an explicit lore-workspace-manifest/1 JSON file");
+  }
+  if (memberIds.some((memberId) => memberId === "")) {
+    throw usage("--repository needs a value", "pass a member id declared by the explicit workspace manifest");
+  }
+  if (rawManifest === undefined) {
+    if (memberIds.length > 0)
+      throw usage("--repository requires --workspace", "select an explicit workspace manifest first");
+    return undefined;
+  }
+  if (new Set(memberIds).size !== memberIds.length) {
+    throw usage("--repository values must be unique", "pass each selected workspace member at most once");
+  }
+  return { manifestPath: rawManifest.trim(), memberIds };
+}
+
+/** A `usage` {@link LoreError} (exit `2`) with an actionable hint. */
+export function usage(message: string, hint: string, input?: unknown): LoreError {
+  return new LoreError("usage", message, hint, input);
+}
+
+/**
+ * Reject a reserved hub stem (`index`/`log`) as a `<action>` target/principal — a `usage` error.
+ * Shared by `rename.ts`, `supersede.ts`, and `link.ts` so the policy (which stems are reserved, and
+ * its wording) can't drift across the three independently. `action` is the verb phrase for the
+ * message, e.g. `"rename to"`, `"supersede"`, `"link"`/`"unlink"`.
+ */
+export function assertNotReservedStem(id: string, action: string): void {
+  if (RESERVED_STEMS.has(posix.basename(id))) {
+    throw usage(
+      `cannot ${action} "${id}": "${posix.basename(id)}" is a reserved, machine-generated file name`,
+      "index.md/log.md are generated by lore, not authored concepts",
+      { id },
+    );
+  }
+}

package/src/commands/changed.ts

@@ -0,0 +1,70 @@
+/** `lore changed`: bounded deterministic retained-snapshot comparison. */
+
+import type { BacklogAdapter } from "../adapters/backlog";
+import { type ChangedResult, compareRetainedSnapshots, type RetainedFactKind } from "../core/snapshot";
+import { resolveSnapshotScope } from "../core/snapshot-runtime";
+import type { SnapshotScopeSelection } from "../core/snapshot-store";
+import { loadSnapshot } from "../core/snapshot-store";
+import { WarningCollector, type Writer } from "../errors";
+import { emit, type OutputContext, type Renderable } from "../output";
+import { optionValues, parseCommandArgs, singleOptionValue, usage, workspaceSelection } from "./args";
+
+export interface ChangedCommandOptions {
+  readonly root: string;
+  readonly output: OutputContext;
+  readonly args: readonly string[];
+  readonly stdout?: Writer;
+  readonly stderr?: Writer;
+  readonly adapter?: BacklogAdapter;
+  readonly resolveScope?: () => SnapshotScopeSelection | Promise<SnapshotScopeSelection>;
+}
+
+export async function runChanged(options: ChangedCommandOptions): Promise<number> {
+  const parsed = parseCommandArgs(options.args, "changed");
+  const workspace = workspaceSelection(parsed);
+  if (parsed.positionals.length !== 2)
+    throw usage("changed needs exactly <from> and <to>", "run `lore changed <from> <to> [--workspace <manifest>]`");
+  const limit = parseLimit(singleOptionValue(parsed, "limit"));
+  const kinds = optionValues(parsed, "kind").map(parseKind);
+  const advisories = new WarningCollector();
+  const selection = workspace === undefined ? {} : { workspace: workspace.manifestPath };
+  const scope =
+    options.resolveScope === undefined
+      ? await resolveSnapshotScope({ root: options.root, selection, warnings: advisories, adapter: options.adapter })
+      : await options.resolveScope();
+  const from = loadSnapshot(options.root, scope, parsed.positionals[0] as string);
+  const to = loadSnapshot(options.root, scope, parsed.positionals[1] as string);
+  const data = compareRetainedSnapshots(from, to, {
+    limit,
+    repositories: workspace?.memberIds ?? [],
+    ...(kinds.length > 0 ? { kinds } : {}),
+  });
+  advisories.flush({ color: options.output.color, stderr: options.stderr });
+  emit(changedRenderable(data), options.output, options.stdout);
+  return 0;
+}
+
+function parseLimit(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  if (!/^[0-9]+$/u.test(raw)) throw usage("--limit must be an integer", "pass a value from 1 through 1000");
+  return Number(raw);
+}
+
+function parseKind(value: string): RetainedFactKind {
+  if (value !== "concept" && value !== "task" && value !== "edge")
+    throw usage(`unknown changed kind ${JSON.stringify(value)}`, "use concept, task, or edge");
+  return value;
+}
+
+function changedRenderable(data: ChangedResult): Renderable<ChangedResult> {
+  return { kind: "changed.result", data, pretty: renderChanged, plain: renderChanged };
+}
+
+function renderChanged(data: ChangedResult): string {
+  const header = `changed ${data.from.snapshotKey}..${data.to.snapshotKey}: ${data.totalChanges} changes, ${data.shown} shown${data.truncated ? " (truncated)" : ""}`;
+  const rows = data.changes.map(
+    (change) =>
+      `${change.change} ${change.recordKind} ${change.id}${change.fieldsChanged.length > 0 ? ` [${change.fieldsChanged.join(",")}]` : ""}`,
+  );
+  return [header, ...rows].join("\n");
+}