@opum-ai/lore 0.1.0 → 0.2.0

package/src/commands/new.ts

@@ -1,476 +0,0 @@
-/**
- * commands/new.ts — `lore new <type> "<title>"`: scaffold a typed concept file.
- *
- * The thin command layer over the pure {@link buildNewConcept} (lore-design §2.2): it parses
- * the command's own arguments, resolves *which* template to render (a user template under
- * `.lore/templates/`, else the built-in for the type), computes the conventional output path,
- * asks core for the bytes, and writes them **never-clobbering** through the shared
- * {@link createIfAbsent}. All side effects (read the template, write the file) live here; all
- * byte computation lives in `core/template.ts`.
- *
- * The two load-bearing behaviors (LORE-18 ACs): a no-flag run renders from a built-in that
- * **validates clean by construction** (AC#1, guaranteed by the templates in core), and a
- * user template at `.lore/templates/<name>.md` **overrides** the built-in wholesale (AC#2).
- * Unlike `init`, an existing target is a `conflict` (exit `5`), not an idempotent skip: `new`
- * creates a *new* concept and must never overwrite or silently no-op onto an existing file.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, join, posix, relative, resolve, sep } from "node:path";
-import { idFromPath } from "../core/concept";
-import { loadProfile, type Profile, templateConfinementViolation } from "../core/profile";
-import { DOCS_DIR } from "../core/scaffold";
-import { canonicalType, isKnownType, SCHEMAS_DIR, schemaFileName, schemaModeline, typeDirectory } from "../core/schema";
-import { buildNewConcept, builtinTemplateFor, slugify } from "../core/template";
-import { EXIT_OK, errnoCode, LoreError, WarningCollector, type Writer } from "../errors";
-import { emit, type OutputContext, type Renderable } from "../output";
-import { assertNotReservedStem, optionValues, parseCommandArgs } from "./args";
-import { createIfAbsent, ensureDir, findSymlinkSegment } from "./fswrite";
-
-/** Where user templates live, relative to the repo root. */
-const TEMPLATES_DIR = ".lore/templates";
-
-/** The reserved bundle-root index `lore init` owns (the sole `okf_version` carrier); `lore new` must not write it. */
-const RESERVED_ROOT_INDEX = `${DOCS_DIR}/index.md`;
-
-/** A valid concept type token: starts with a letter, then letters/digits/dashes/underscores — no spaces or path separators. */
-const VALID_TYPE = /^[A-Za-z][A-Za-z0-9_-]*$/;
-
-/**
- * The stub `summary` injected when no `--summary` is given. Short and present, so a no-flag
- * run validates clean (a missing or over-long summary would warn), while clearly flagging
- * the one line the author should replace.
- */
-const SUMMARY_STUB = "Add a one-line summary of this concept.";
-
-/** The result of a `new` run: the created concept's id, path, and type. */
-export interface NewResult {
-  /** The new concept's bundle-relative id (path under `docs/` minus `.md`), e.g. `stories/bulk-archive`. */
-  id: string;
-  /** The repo-relative POSIX path written, e.g. `docs/stories/bulk-archive.md`. */
-  path: string;
-  /** The resolved concept `type` (canonical for a known type, verbatim for a producer extension). */
-  type: string;
-}
-
-/** Options for {@link runNew}; `root`, `clock`, and the streams are injectable for tests. */
-export interface NewOptions {
-  /** The repo root to scaffold into. */
-  root: string;
-  /** The resolved output mode/color (from `output.ts`). */
-  output: OutputContext;
-  /** The command's normalized positional + flag tokens from Commander. */
-  args: readonly string[];
-  /** Clock seam for the `timestamp` token; defaults to the real wall clock. */
-  clock?: () => Date;
-  /** stdout sink; defaults to `process.stdout`. */
-  stdout?: Writer;
-  /** stderr sink for advisory warnings; defaults to `process.stderr`. */
-  stderr?: Writer;
-}
-
-/** The parsed form of `lore new`'s arguments. */
-interface NewArgs {
-  type: string;
-  title: string;
-  vars: Record<string, string>;
-  template?: string;
-  summary?: string;
-  tags?: string;
-  out?: string;
-}
-
-/**
- * Run `lore new`: parse the arguments, resolve the template, render the concept, and write it
- * never-clobbering. Returns the exit code (`0`). A missing positional or bad flag throws a
- * `usage` {@link LoreError} (exit `2`); an unfilled `{{placeholder}}` or invalid frontmatter a
- * `validation` error (exit `6`); an existing target a `conflict` (exit `5`).
- */
-export function runNew(options: NewOptions): number {
-  const clock = options.clock ?? (() => new Date());
-  const parsed = parseNewArgs(options.args);
-  const profile = loadProfile({ root: options.root });
-  const type = canonicalType(parsed.type, profile);
-  // A profile-declared type is valid by definition — including a multi-word/space-containing name
-  // like "QA Plan" (its path segments come from the LOWER-KEBAB slug, which is always safe). The
-  // VALID_TYPE shape check only gates an *ad-hoc* unknown type, whose raw token would otherwise
-  // become a directory/filename segment verbatim.
-  if (!isKnownType(type, profile) && !VALID_TYPE.test(type)) {
-    throw usage(
-      `"${parsed.type}" is not a valid type`,
-      "a type must start with a letter and contain only letters, digits, dashes, or underscores — or be declared in .lore/profile.toml",
-    );
-  }
-
-  const docPath = resolveDocPath(parsed, type, options.root);
-  const bodyTemplate = resolveTemplate(parsed, type, options.root, profile);
-
-  const build = buildNewConcept({
-    docPath,
-    type,
-    title: parsed.title,
-    summary: parsed.summary ?? SUMMARY_STUB,
-    timestamp: clock().toISOString(),
-    tags: parseTags(parsed.tags),
-    bodyTemplate,
-    vars: parsed.vars,
-    modeline: resolveModeline(type, docPath, options.root, profile),
-    profile,
-  });
-
-  const absPath = join(options.root, docPath);
-  // Check for an existing target before creating any parent directories, so an aborted
-  // (conflicting) run leaves no empty scaffold dirs behind. `createIfAbsent`'s atomic `wx`
-  // write remains the authority that closes the time-of-check/time-of-use race.
-  if (existsSync(absPath)) {
-    throw conflict(docPath);
-  }
-  ensureDir(options.root, posix.dirname(docPath));
-  if (!createIfAbsent(absPath, build.contents, docPath)) {
-    throw conflict(docPath);
-  }
-
-  flushWarnings(build.warnings, options.output, options.stderr);
-  emit(newRenderable({ id: bundleId(docPath), path: docPath, type: build.type }), options.output, options.stdout);
-  return EXIT_OK;
-}
-
-/** A `conflict` {@link LoreError} (exit `5`) for a target path that already exists. */
-function conflict(docPath: string): LoreError {
-  return new LoreError(
-    "conflict",
-    `${docPath} already exists`,
-    "choose a different title, pass --out <path>, or remove the existing file",
-    { path: docPath },
-  );
-}
-
-/**
- * The editor modeline for a known type whose exported schema actually exists on disk, else
- * `undefined`. An unknown type has no schema; a doc written into a never-`init`-ed bundle has no
- * `.lore/schemas/` either — in both cases lore writes no modeline rather than one pointing at a
- * `$schema` file that is not there.
- */
-function resolveModeline(type: string, docPath: string, root: string, profile: Profile): string | undefined {
-  if (!isKnownType(type, profile)) {
-    return undefined;
-  }
-  if (!existsSync(join(root, SCHEMAS_DIR, schemaFileName(type)))) {
-    return undefined;
-  }
-  return schemaModeline(docPath, type);
-}
-
-// ── Argument parsing ───────────────────────────────────────────────────────────
-
-/**
- * Parse `new`'s tokens into positionals (`<type> <title>`) and its flags. The router has
- * already stripped lore's global flags, so anything `--`-prefixed here is a command flag: an
- * unrecognized one is a `usage` error, as is a malformed `--var` or the wrong positional count.
- * Both `--flag value` and `--flag=value` forms are accepted; a value-taking flag refuses to
- * consume a following flag-looking token as its value (so `--summary --tags x` reports the
- * missing summary value rather than silently eating `--tags`). A `--` ends option parsing so a
- * title may begin with `-` (`lore new adr -- "-5 minute timeout"`).
- */
-function parseNewArgs(args: readonly string[]): NewArgs {
-  const parsed = parseCommandArgs(args, "new");
-  const positionals = parsed.positionals;
-  const vars: Record<string, string> = Object.create(null);
-  for (const raw of optionValues(parsed, "var")) addVar(vars, raw);
-  const template = optionValues(parsed, "template").at(-1);
-  const summary = optionValues(parsed, "summary").at(-1);
-  const tags = optionValues(parsed, "tags").at(-1);
-  const out = optionValues(parsed, "out").at(-1);
-
-  const type = positionals[0];
-  if (type === undefined || type.trim() === "") {
-    throw usage("`lore new` needs a type", 'run `lore new <type> "<title>"`, e.g. lore new adr "Use soft deletes"');
-  }
-  const title = positionals[1];
-  if (title === undefined || title.trim() === "") {
-    throw usage("`lore new` needs a title", 'run `lore new <type> "<title>"` with a quoted title');
-  }
-  if (positionals.length > 2) {
-    throw usage(
-      `unexpected argument "${positionals[2]}"`,
-      'pass exactly a type and a title; quote a multi-word title: lore new <type> "<title>"',
-    );
-  }
-  return { type: type.trim(), title: title.trim(), vars, template, summary, tags, out };
-}
-
-/**
- * Record one `--var key=value` pair. The key must be a non-empty placeholder name
- * (`[A-Za-z0-9_.-]+`, the {@link renderTemplate} token grammar); the value is everything
- * after the first `=` (so it may itself contain `=`). `vars` is a null-prototype object, so a
- * key like `__proto__` lands as an own property without polluting any prototype.
- */
-function addVar(vars: Record<string, string>, raw: string): void {
-  const eq = raw.indexOf("=");
-  if (eq <= 0) {
-    throw usage(`--var must be key=value, got "${raw}"`, "supply a non-empty key, e.g. --var owner=payments");
-  }
-  const key = raw.slice(0, eq);
-  if (!/^[A-Za-z0-9_.-]+$/.test(key)) {
-    throw usage(
-      `--var key "${key}" is not a valid placeholder name`,
-      "use letters, digits, dots, dashes, or underscores for the key",
-    );
-  }
-  vars[key] = raw.slice(eq + 1);
-}
-
-/** Split a `--tags a,b,c` value into a trimmed, non-empty list (absent flag → `undefined`). */
-function parseTags(tags: string | undefined): string[] | undefined {
-  if (tags === undefined) {
-    return undefined;
-  }
-  return tags
-    .split(",")
-    .map((tag) => tag.trim())
-    .filter((tag) => tag !== "");
-}
-
-// ── Path + template resolution ───────────────────────────────────────────────────
-
-/**
- * Compute the new doc's repo-relative POSIX path. With `--out` the caller's path wins
- * (resolved and confined to the repo by {@link resolveOutPath}); otherwise it is the
- * conventional `docs/<typeDirectory>/<slug-of-title>.md`. A title with no slug-able content
- * and no `--out` is a `usage` error rather than a `-.md` file.
- *
- * The default path is checked against the same {@link assertNotReservedStem} guard
- * {@link resolveOutPath} applies (LORE-174): a title that slugifies to `index` or `log` (e.g.
- * `lore new reference "Index"`) would otherwise land on a stem `rename`/`supersede`/`link` treat
- * as lore-generated and refuse to touch, bypassing the policy LORE-114 added only on the `--out`
- * path. The default path always carries a non-empty type-directory segment (every known
- * {@link typeDirectory} maps to a non-empty string, and every ad-hoc type's slug is non-empty
- * since `VALID_TYPE` requires a leading letter), so it can never collide with the bundle-root
- * index `resolveOutPath` guards separately — no `RESERVED_ROOT_INDEX` check is needed here.
- */
-function resolveDocPath(parsed: NewArgs, type: string, root: string): string {
-  if (parsed.out !== undefined) {
-    return resolveOutPath(parsed.out, root);
-  }
-  const slug = slugify(parsed.title);
-  if (slug === "") {
-    throw usage(`could not derive a filename from title "${parsed.title}"`, "pass an explicit path with --out <path>");
-  }
-  const docPath = posix.join(DOCS_DIR, typeDirectory(type), `${slug}.md`);
-  assertNotReservedStem(idFromPath(docPath), "create");
-  return docPath;
-}
-
-/**
- * Resolve a `--out` value to a repo-relative POSIX path, confining it to the **bundle root**
- * (`docs/`) and ending it in `.md` (appended when omitted). A path that escapes the repo
- * (`../…`, an absolute path elsewhere), lands outside `docs/`, or targets the reserved
- * bundle-root index (`docs/index.md`, owned by `lore init`) is a `usage` error — so `lore new`
- * can never write an orphaned file the bundle walk won't see, nor clobber the conformance root.
- * The `..` escape is matched by path **segment** (`..` exactly or a leading `../`), so a real
- * in-repo path whose first segment merely starts with `..` (e.g. `..notes/x`) is not rejected.
- *
- * Beyond the root index, ANY basename of `index`/`log` — at any nesting depth — is also rejected,
- * via the same {@link assertNotReservedStem} `rename`/`supersede`/`link` share (LORE-114): those
- * stems are lore's own generated file names wherever they sit, not just at the bundle root, so
- * `lore new` must not let a user create a doc that collides with one. Checked AFTER the
- * root-index-specific check above, so `docs/index.md` keeps its own message unaffected.
- */
-function resolveOutPath(out: string, root: string): string {
-  const rel = relative(root, resolve(root, out));
-  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-    throw usage(`--out path "${out}" must be inside the repo`, "give a path relative to the repo root");
-  }
-  let posixRel = rel.split(sep).join("/");
-  if (!posixRel.endsWith(".md")) {
-    posixRel = `${posixRel}.md`;
-  }
-  if (posixRel !== DOCS_DIR && !posixRel.startsWith(`${DOCS_DIR}/`)) {
-    throw usage(
-      `--out path "${out}" must be inside the bundle root (${DOCS_DIR}/)`,
-      `give a path under ${DOCS_DIR}/, e.g. --out ${DOCS_DIR}/reference/orders.md`,
-    );
-  }
-  if (posixRel === RESERVED_ROOT_INDEX) {
-    throw usage(
-      `${RESERVED_ROOT_INDEX} is the reserved bundle-root index`,
-      "choose another path; `lore init` owns the root index that carries okf_version",
-    );
-  }
-  assertNotReservedStem(idFromPath(posixRel), "create");
-  return posixRel;
-}
-
-/**
- * Resolve the template text. The file base is `--template <name>` when given, else the type;
- * the file is `.lore/templates/<base>.md`. The base precedence is: an explicit `--template <name>`,
- * else the **profile type's declared `template`** (its filename minus `.md`), else the type name.
- * To be correct on **case-sensitive** filesystems (Linux/CI) while staying convenient on
- * case-insensitive ones, the lookup tries the name as given (e.g. `Reference.md`, matching the
- * docs' canonical-case `<type>` spelling) and then its lower-cased form (`reference.md`, matching
- * the schema filenames). A present file is the user template (override, AC#2). If none exists: an
- * explicit `--template` is a `not_found` error (the caller asked for a specific template); a
- * profile-declared-but-missing template, like the default, falls back to the built-in body.
- *
- * An explicit `--template` is a user-facing CLI flag (unlike `declared`, a repo-config value) and
- * is validated with {@link assertTemplateNameConfined} BEFORE it ever reaches a file path (LORE-69):
- * `--template` is documented as a bare name, never a path, so a `..` segment or an absolute value
- * is rejected outright rather than spliced into `${TEMPLATES_DIR}/${base}.md` and hoped safe. The
- * profile-declared `template` went through the analogous {@link templateConfinementViolation}
- * check already, at profile PARSE time (LORE-139), so it is not re-checked for confinement here —
- * only the two named-by-user-or-repo-config sources (`--template`, `declared`) get the symlink
- * refusal below; the bare-type-name convention lookup (neither given) does not (LORE-91 scope).
- */
-function resolveTemplate(parsed: NewArgs, type: string, root: string, profile: Profile): string {
-  const explicitTemplate = parsed.template !== undefined;
-  if (parsed.template !== undefined) {
-    assertTemplateNameConfined(parsed.template);
-  }
-  const declared = profile.types.get(type)?.template?.replace(/\.md$/i, "");
-  const base = parsed.template ?? declared ?? type;
-  // A named template source — the CLI flag or a profile's own declared filename — is refused if
-  // it resolves through a symlink (LORE-91, widened to `declared` by LORE-185's AC#2); the bare
-  // type-name convention lookup below carries no such refusal, matching the pre-LORE-185 scope.
-  const checkSymlink = explicitTemplate || declared !== undefined;
-  for (const candidate of templateCandidates(base)) {
-    const relPath = `${TEMPLATES_DIR}/${candidate}.md`;
-    const text = readTemplateFile(join(root, relPath), relPath, root, checkSymlink);
-    if (text !== undefined) {
-      return text;
-    }
-  }
-  if (parsed.template !== undefined) {
-    throw new LoreError(
-      "not_found",
-      `template "${parsed.template}" not found in ${TEMPLATES_DIR}/`,
-      `create ${TEMPLATES_DIR}/${parsed.template}.md, or omit --template to use the built-in`,
-      { path: `${TEMPLATES_DIR}/${parsed.template}.md` },
-    );
-  }
-  return builtinTemplateFor(type);
-}
-
-/**
- * Reject a `--template` value that could escape `.lore/templates/` once spliced into a file
- * path, via the shared {@link templateConfinementViolation} predicate `core/profile.ts` also uses
- * for the profile-declared `[[types]].template` value (LORE-139) — LORE-185 consolidated what
- * used to be this function's own host-`resolve()`/`relative()` arithmetic (no backslash
- * normalization) onto that one pure-posix, backslash-aware implementation, closing a cross-host
- * drift: a Windows-style `--template ..\..\secret` escape was only ever caught on an actual win32
- * run before — a POSIX test/CI run saw it as one inert, non-escaping filename segment — and is now
- * rejected identically on every host. See {@link templateConfinementViolation}'s own docstring for
- * the absolute-path and `..`-escape rationale in full (both apply unchanged here).
- */
-function assertTemplateNameConfined(name: string): void {
-  const violation = templateConfinementViolation(name);
-  if (violation === "absolute") {
-    throw usage(
-      `--template value "${name}" must not be an absolute path`,
-      "pass a bare template name, e.g. --template adr",
-    );
-  }
-  if (violation === "escape") {
-    throw usage(
-      `--template value "${name}" must not escape ${TEMPLATES_DIR}/`,
-      "pass a bare template name, e.g. --template adr",
-    );
-  }
-}
-
-/** The template filenames to try for a base, the name as given first then its lower-cased form (deduped). */
-function templateCandidates(base: string): string[] {
-  const lower = base.toLowerCase();
-  return base === lower ? [base] : [base, lower];
-}
-
-/**
- * Read a template file as UTF-8, returning `undefined` when it does not exist (`ENOENT`) so
- * the caller can fall back to a built-in. A permission failure becomes a `denied`
- * {@link LoreError}; any other read fault propagates as an uncaught error.
- *
- * `checkSymlink` (true for an explicit `--template` (LORE-91) AND, as of LORE-185's AC#2, a
- * profile-declared `template` — `resolveTemplate`'s `declared` fallback) refuses — rather than
- * silently reading through — a symlinked candidate anywhere in `relPath`'s segments, closing an
- * information-disclosure gap the purely syntactic {@link templateConfinementViolation} containment
- * check cannot: a bare, unsuspicious `--template evil` (or a profile declaring `template = "evil"`)
- * whose resolved `.lore/templates/evil.md` is itself a symlink to an arbitrary file outside the
- * repo would otherwise have that file's exact content silently embedded in the generated concept.
- * Mirrors this codebase's established write-path precedent (`fswrite.ts`'s
- * `assertNoSymlinkInPath`/`findSymlinkSegment`, LORE-76/77) rather than inventing a new pattern,
- * and its own READ-path precedent (`core/bundle.ts`'s `walkMarkdown`, `commands/replace.ts`) of
- * never following a symlink that could resolve outside the repo. `checkSymlink` is still `false`
- * for the bare-type-name convention lookup (neither `--template` nor a profile `declared` value) —
- * LORE-139 hardened that path's PARSE-time traversal check (via the profile's own compiled
- * `template`, confined before `resolveTemplate` ever sees it) but, unlike the two named sources
- * above, that implicit lookup names no untrusted value at all, so it was intentionally left out of
- * this task's AC#2 scope rather than "left untouched" wholesale, as an earlier draft of this
- * comment (pre-LORE-185) claimed.
- */
-function readTemplateFile(absPath: string, relPath: string, root: string, checkSymlink: boolean): string | undefined {
-  if (checkSymlink) {
-    const symlink = findSymlinkSegment(root, relPath);
-    if (symlink !== null) {
-      throw new LoreError(
-        "conflict",
-        `refusing to read ${relPath}: "${symlink}" is a symlink, not a real directory or file`,
-        "lore does not read through a symlink (it may resolve outside the repo) — remove or replace it, then re-run",
-        { path: relPath, symlink },
-      );
-    }
-  }
-  try {
-    return readFileSync(absPath, "utf8");
-  } catch (cause) {
-    const code = errnoCode(cause);
-    if (code === "ENOENT") {
-      return undefined;
-    }
-    if (code === "EACCES" || code === "EPERM") {
-      throw new LoreError("denied", `permission denied reading ${relPath}`, `make ${relPath} readable`, {
-        path: relPath,
-        code,
-      });
-    }
-    throw cause;
-  }
-}
-
-// ── Output ───────────────────────────────────────────────────────────────────────
-
-/** The bundle-relative id for a written doc: the path under `docs/` minus `.md`. */
-function bundleId(docPath: string): string {
-  const prefix = `${DOCS_DIR}/`;
-  return idFromPath(docPath.startsWith(prefix) ? docPath.slice(prefix.length) : docPath);
-}
-
-/** Flush advisory warnings to stderr in the shared `warning:` format (non-fatal; never changes the exit code). */
-function flushWarnings(warnings: readonly string[], output: OutputContext, stderr: Writer | undefined): void {
-  if (warnings.length === 0) {
-    return;
-  }
-  const collector = new WarningCollector();
-  for (const warning of warnings) {
-    collector.add(warning);
-  }
-  collector.flush({ color: output.color, stderr });
-}
-
-/** The per-result-type rendering bundle for `new` (output.ts dispatches on the mode). */
-function newRenderable(data: NewResult): Renderable<NewResult> {
-  return { kind: "new", data, pretty: renderPretty, plain: renderPlain };
-}
-
-/** Human view: a one-line confirmation naming the type, id, and path. */
-function renderPretty(data: NewResult): string {
-  return `Created ${data.type} ${data.id}\n  ${data.path}`;
-}
-
-/** ANSI-free, diff-stable view: one `created <path>` line. */
-function renderPlain(data: NewResult): string {
-  return `created ${data.path}`;
-}
-
-/** A `usage` {@link LoreError} (exit `2`) with an actionable hint. */
-function usage(message: string, hint: string): LoreError {
-  return new LoreError("usage", message, hint);
-}