kennel 0.2.32 → 0.2.34

package/dist/notes/command.js

@@ -0,0 +1,556 @@
+// packages/notes/src/store.ts
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  stat,
+  writeFile
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var REPOSITORY_ID_KEY = "kennel.repoId";
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+var markdownExtensions = new Set([".md", ".markdown"]);
+var caseInsensitiveHosts = new Set(["github.com", "gitlab.com", "bitbucket.org"]);
+var indexLockStaleMs = 30000;
+var indexLockAttempts = 100;
+var indexLockWaitMs = 50;
+
+class RepositoryNotesError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RepositoryNotesError";
+    this.code = code;
+  }
+}
+function kennelConfigHome() {
+  const xdg = process.env.XDG_CONFIG_HOME?.trim();
+  return xdg ? xdg : join(homedir(), ".config");
+}
+function kennelConfigFile() {
+  return join(kennelConfigHome(), "kennel", "config.json");
+}
+function repositoryNotesRoot() {
+  return join(kennelConfigHome(), "kennel", "repos");
+}
+function repositoryIndexFile() {
+  return join(repositoryNotesRoot(), "index.json");
+}
+function isRepositoryId(value) {
+  return typeof value === "string" && UUID.test(value);
+}
+function managedNotesDirectory(id) {
+  if (!isRepositoryId(id)) {
+    throw new RepositoryNotesError("invalid-id", `Invalid repository id: ${id}`);
+  }
+  return join(repositoryNotesRoot(), id);
+}
+function enableHint() {
+  return `Enable repository notes by adding {"repositoryNotes":{"enabled":true}} to ${kennelConfigFile()} (keep the other keys of that file).`;
+}
+async function readRepositoryNotesSettings() {
+  const file = kennelConfigFile();
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { enabled: false };
+    }
+    throw new RepositoryNotesError("config-invalid", `Cannot read ${file}: ${errorMessage(error)}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new RepositoryNotesError("config-invalid", `Invalid JSON in ${file}: ${errorMessage(error)}`);
+  }
+  if (!isRecord(value)) {
+    throw new RepositoryNotesError("config-invalid", `${file} must hold an object`);
+  }
+  const section = value.repositoryNotes;
+  if (section === undefined)
+    return { enabled: false };
+  if (!isRecord(section) || section.enabled !== undefined && typeof section.enabled !== "boolean") {
+    throw new RepositoryNotesError("config-invalid", `${file}: repositoryNotes must be an object with a boolean "enabled" field`);
+  }
+  return { enabled: section.enabled === true };
+}
+async function git(args, cwd) {
+  const { stdout } = await run("git", args, {
+    cwd,
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
+    maxBuffer: 1024 * 1024
+  });
+  return stdout.replace(/\r?\n$/u, "");
+}
+function gitExitCode(error) {
+  const code = error.code;
+  return typeof code === "number" ? code : undefined;
+}
+async function resolveCheckout(folder) {
+  let start;
+  try {
+    start = await realpath(resolve(folder));
+    if (!(await stat(start)).isDirectory())
+      start = dirname(start);
+  } catch {
+    throw new RepositoryNotesError("not-git", `Folder does not exist: ${folder}`);
+  }
+  let output;
+  try {
+    output = await git(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], start);
+  } catch (error) {
+    if (gitExitCode(error) === 128) {
+      throw new RepositoryNotesError("not-git", `Not a Git repository: ${start}. Repository notes need a Git checkout.`);
+    }
+    throw error;
+  }
+  const [top, common] = output.split(/\r?\n/u);
+  if (!top || !common) {
+    throw new RepositoryNotesError("not-git", `Not a Git work tree: ${start}`);
+  }
+  const root = await realpath(top);
+  const commonDir = await realpath(common);
+  return { root, commonDir, configFile: join(commonDir, "config") };
+}
+async function readBinding(checkout) {
+  let value;
+  try {
+    value = await git(["config", "--file", checkout.configFile, "--get", REPOSITORY_ID_KEY], checkout.root);
+  } catch (error) {
+    if (gitExitCode(error) === 1)
+      return;
+    throw error;
+  }
+  const id = value.trim();
+  if (!id)
+    return;
+  if (!isRepositoryId(id)) {
+    throw new RepositoryNotesError("invalid-binding", `${checkout.configFile} has an invalid ${REPOSITORY_ID_KEY} value. Remove it or run "kennel notes new-identity".`);
+  }
+  return id;
+}
+async function writeBinding(checkout, id) {
+  await git(["config", "--file", checkout.configFile, REPOSITORY_ID_KEY, id], checkout.root);
+}
+function redactRemoteUrl(url) {
+  return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/iu, "$1").replace(/^[^@/:\s]+@([^:/\s]+:)/u, "$1");
+}
+function isLocalPath(url) {
+  return url.startsWith("/") || url.startsWith("./") || url.startsWith("../") || url.startsWith("~") || url === "." || url === ".." || /^[A-Za-z]:[\\/]/u.test(url) || /^file:/iu.test(url);
+}
+function normalizeHost(host) {
+  const bare = host.replace(/^\[|\]$/gu, "");
+  return bare.includes(".") || bare.includes(":") || bare === "localhost" ? bare.toLowerCase() : bare;
+}
+function normalizePath(path, host) {
+  let value = path.replace(/\/{2,}/gu, "/").replace(/^\/+/u, "").replace(/\/+$/u, "");
+  if (value.endsWith(".git"))
+    value = value.slice(0, -4);
+  value = value.replace(/\/+$/u, "");
+  if (caseInsensitiveHosts.has(host))
+    value = value.toLowerCase();
+  return value;
+}
+function normalizeRemoteAlias(url) {
+  const trimmed = url.trim();
+  const reject = (reason) => {
+    throw new RepositoryNotesError("unsupported-remote", `Unsupported remote URL ${redactRemoteUrl(trimmed)}: ${reason}. Use "kennel notes new-identity" for a local-only collection.`);
+  };
+  if (!trimmed || /[\s\u0000-\u001f\u007f]/u.test(trimmed))
+    reject("it is empty or contains whitespace");
+  if (isLocalPath(trimmed))
+    reject("local paths and file URLs have no shared address");
+  const scheme = /^([a-z][a-z0-9+.-]*):\/\//iu.exec(trimmed);
+  if (scheme) {
+    const name = scheme[1].toLowerCase();
+    const defaultPorts = {
+      "git+ssh": "22",
+      "ssh+git": "22",
+      git: "9418",
+      http: "80",
+      https: "443",
+      ssh: "22"
+    };
+    if (!(name in defaultPorts))
+      reject(`the ${name} scheme is not supported`);
+    let parsed;
+    try {
+      parsed = new URL(trimmed);
+    } catch {
+      return reject("it is not a valid URL");
+    }
+    if (!parsed.hostname)
+      reject("it has no host");
+    const host = normalizeHost(parsed.hostname);
+    const port = parsed.port && parsed.port !== defaultPorts[name] ? `:${parsed.port}` : "";
+    const path = normalizePath(decodeURIComponent(parsed.pathname), host);
+    if (!path)
+      reject("it has no repository path");
+    return `${host}${port}/${path}`;
+  }
+  const scp = /^(?:[^@/:\s]+@)?([^:/\s]+):(.+)$/u.exec(trimmed);
+  if (scp) {
+    const host = normalizeHost(scp[1]);
+    const path = normalizePath(scp[2], host);
+    if (!path)
+      reject("it has no repository path");
+    return `${host}/${path}`;
+  }
+  return reject("only ssh://, https://, http://, git:// and user@host:path forms are supported");
+}
+async function selectRemote(checkout, preferred) {
+  const names = (await git(["remote"], checkout.root)).split(/\r?\n/u).filter(Boolean);
+  let name;
+  if (preferred !== undefined) {
+    if (!names.includes(preferred)) {
+      throw new RepositoryNotesError("ambiguous-remote", `Remote "${preferred}" does not exist. Remotes: ${names.join(", ") || "none"}.`);
+    }
+    name = preferred;
+  } else if (names.includes("origin")) {
+    name = "origin";
+  } else if (names.length === 1) {
+    name = names[0];
+  } else if (names.length > 1) {
+    throw new RepositoryNotesError("ambiguous-remote", `Several remotes and no origin (${names.join(", ")}). Choose one with --remote <name>.`);
+  }
+  if (!name)
+    return;
+  const url = await git(["remote", "get-url", name], checkout.root);
+  return { alias: normalizeRemoteAlias(url), name };
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function malformedIndex(detail) {
+  throw new RepositoryNotesError("index-malformed", `Malformed repository notes index ${repositoryIndexFile()}: ${detail}. Repair the file; Kennel does not replace it.`);
+}
+async function readRepositoryIndex() {
+  let text;
+  try {
+    text = await readFile(repositoryIndexFile(), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { version: 1, repositories: {} };
+    }
+    throw error;
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    return malformedIndex(errorMessage(error));
+  }
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.repositories)) {
+    malformedIndex('expected {"version":1,"repositories":{...}}');
+  }
+  const repositories = {};
+  const owners = new Map;
+  for (const [id, entry] of Object.entries(value.repositories)) {
+    if (!isRepositoryId(id))
+      malformedIndex(`"${id}" is not a repository id`);
+    if (!isRecord(entry) || !Array.isArray(entry.aliases)) {
+      malformedIndex(`entry ${id} needs an aliases array`);
+    }
+    const aliases = [];
+    for (const alias of entry.aliases) {
+      if (typeof alias !== "string" || !alias.trim())
+        malformedIndex(`entry ${id} has an invalid alias`);
+      const owner = owners.get(alias);
+      if (owner && owner !== id)
+        malformedIndex(`alias ${alias} belongs to ${owner} and ${id}`);
+      owners.set(alias, id);
+      if (!aliases.includes(alias))
+        aliases.push(alias);
+    }
+    repositories[id] = {
+      aliases,
+      createdAt: typeof entry.createdAt === "string" ? entry.createdAt : new Date(0).toISOString(),
+      ...typeof entry.name === "string" ? { name: entry.name } : {}
+    };
+  }
+  return { version: 1, repositories };
+}
+async function writeRepositoryIndex(index) {
+  const file = repositoryIndexFile();
+  const temporary = join(dirname(file), `.index-${process.pid}-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, `${JSON.stringify(index, null, 2)}
+`, { flag: "wx" });
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+async function withIndexLock(action) {
+  const root = repositoryNotesRoot();
+  await mkdir(root, { recursive: true });
+  const lock = join(root, "index.lock");
+  for (let attempt = 0;attempt < indexLockAttempts; attempt += 1) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      const details = await stat(lock).catch(() => {
+        return;
+      });
+      if (details && Date.now() - details.mtimeMs > indexLockStaleMs) {
+        await rm(lock, { force: true, recursive: true });
+        continue;
+      }
+      if (attempt === indexLockAttempts - 1) {
+        throw new RepositoryNotesError("index-locked", `Another registration holds ${lock}. Retry, or remove the lock if no Kennel process is running.`);
+      }
+      await new Promise((done) => setTimeout(done, indexLockWaitMs));
+    }
+  }
+  try {
+    return await action();
+  } finally {
+    await rm(lock, { force: true, recursive: true });
+  }
+}
+function aliasOwner(index, alias) {
+  return Object.entries(index.repositories).find(([, entry]) => entry.aliases.includes(alias))?.[0];
+}
+function displayName(alias, root) {
+  return basename(alias ?? root);
+}
+async function assertEnabled() {
+  const settings = await readRepositoryNotesSettings();
+  if (!settings.enabled) {
+    throw new RepositoryNotesError("disabled", `Repository notes are disabled. ${enableHint()}`);
+  }
+}
+async function bindAndCreate(checkout, id, alias) {
+  try {
+    await writeBinding(checkout, id);
+  } catch (error) {
+    throw new RepositoryNotesError("partial-registration", `The index records ${id}${alias ? ` for ${alias}` : ""}, but writing ${REPOSITORY_ID_KEY} to ${checkout.configFile} failed: ${errorMessage(error)}. The checkout is not bound; run the command again.`);
+  }
+  const notesDirectory = managedNotesDirectory(id);
+  await mkdir(notesDirectory, { recursive: true });
+  return { id, notesDirectory, root: checkout.root, ...alias ? { alias } : {} };
+}
+async function ensureRepositoryNotes(folder, options = {}) {
+  const checkout = await resolveCheckout(folder);
+  await assertEnabled();
+  const bound = await readBinding(checkout);
+  if (bound) {
+    const notesDirectory = managedNotesDirectory(bound);
+    await mkdir(notesDirectory, { recursive: true });
+    return { id: bound, notesDirectory, root: checkout.root };
+  }
+  const remote = await selectRemote(checkout, options.remote);
+  return withIndexLock(async () => {
+    const raced = await readBinding(checkout);
+    if (raced)
+      return bindAndCreate(checkout, raced, undefined);
+    const index = await readRepositoryIndex();
+    const known = remote ? aliasOwner(index, remote.alias) : undefined;
+    const id = known ?? randomUUID();
+    if (!known) {
+      index.repositories[id] = {
+        aliases: remote ? [remote.alias] : [],
+        createdAt: new Date().toISOString(),
+        name: displayName(remote?.alias, checkout.root)
+      };
+      await writeRepositoryIndex(index);
+    }
+    return bindAndCreate(checkout, id, remote?.alias);
+  });
+}
+async function bindRepositoryNotes(folder, id, options = {}) {
+  if (!isRepositoryId(id)) {
+    throw new RepositoryNotesError("invalid-id", `Invalid repository id: ${id}`);
+  }
+  const checkout = await resolveCheckout(folder);
+  await assertEnabled();
+  const bound = await readBinding(checkout);
+  if (bound && bound !== id && !options.replace) {
+    throw new RepositoryNotesError("binding-conflict", `${checkout.root} is already bound to ${bound}. Pass --replace to bind it to ${id} instead; notes are not moved or merged.`);
+  }
+  const remote = options.recordAlias === false ? undefined : await selectRemote(checkout, options.remote);
+  return withIndexLock(async () => {
+    const index = await readRepositoryIndex();
+    const exists = Boolean(index.repositories[id]) || await stat(managedNotesDirectory(id)).then((details) => details.isDirectory()).catch(() => false);
+    if (!exists) {
+      throw new RepositoryNotesError("unknown-id", `Unknown repository id ${id}: it is not in the index and has no notes directory.`);
+    }
+    if (remote) {
+      const owner = aliasOwner(index, remote.alias);
+      if (owner && owner !== id) {
+        throw new RepositoryNotesError("alias-conflict", `Remote ${remote.alias} already belongs to collection ${owner}. Pass --no-alias to bind without recording this address.`);
+      }
+      const entry = index.repositories[id] ??= {
+        aliases: [],
+        createdAt: new Date().toISOString(),
+        name: displayName(remote.alias, checkout.root)
+      };
+      if (!owner) {
+        entry.aliases.push(remote.alias);
+        await writeRepositoryIndex(index);
+      }
+    }
+    return bindAndCreate(checkout, id, remote?.alias);
+  });
+}
+async function newRepositoryIdentity(folder, options = {}) {
+  const checkout = await resolveCheckout(folder);
+  await assertEnabled();
+  const previousId = await readBinding(checkout);
+  const remote = await selectRemote(checkout, options.remote);
+  return withIndexLock(async () => {
+    const index = await readRepositoryIndex();
+    const id = randomUUID();
+    const owner = remote ? aliasOwner(index, remote.alias) : undefined;
+    const alias = remote && !owner ? remote.alias : undefined;
+    index.repositories[id] = {
+      aliases: alias ? [alias] : [],
+      createdAt: new Date().toISOString(),
+      name: displayName(remote?.alias, checkout.root)
+    };
+    await writeRepositoryIndex(index);
+    const destination = await bindAndCreate(checkout, id, alias);
+    return {
+      ...destination,
+      ...owner ? { aliasOwner: owner } : {},
+      ...previousId ? { previousId } : {}
+    };
+  });
+}
+
+// packages/cli/src/notes/command.ts
+var USAGE = `Usage:
+  kennel notes path [folder] [--json] [--remote <name>]
+  kennel notes bind <uuid> [folder] [--json] [--remote <name>] [--replace] [--no-alias]
+  kennel notes new-identity [folder] [--json] [--remote <name>]
+  kennel notes --help
+
+Repository notes live in \${XDG_CONFIG_HOME:-$HOME/.config}/kennel/repos/<uuid>/.
+The feature is opt-in: {"repositoryNotes":{"enabled":true}} in kennel/config.json.
+
+  path          Resolve and create the notes folder of the Git repository that
+                contains the folder (default: the current directory). Plain
+                output is the absolute folder; --json adds id and root. A new
+                checkout reuses the collection of its normalized origin (or sole)
+                remote, or gets a new id. The binding is kennel.repoId in the
+                shared local Git config. Nothing is moved, fetched, or published.
+  bind          Bind a checkout to an existing collection, for renamed remotes or
+                fresh clones. --replace changes an existing different binding.
+                The current remote address is recorded as an alias unless
+                --no-alias is given; an address owned by another collection fails.
+  new-identity  Start a new collection for this checkout. Existing notes stay.
+  --remote      Choose the remote when there are several and no origin.
+
+Errors go to stderr with a nonzero exit status. Non-Git folders are an error.
+`;
+function usageError(message) {
+  throw new Error(`${message}
+Run kennel notes --help for usage.`);
+}
+function parseArgs(args) {
+  const options = { folder: ".", help: false, json: false, recordAlias: true, replace: false };
+  const positionals = [];
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-h" || arg === "--help")
+      options.help = true;
+    else if (arg === "--json")
+      options.json = true;
+    else if (arg === "--replace")
+      options.replace = true;
+    else if (arg === "--no-alias")
+      options.recordAlias = false;
+    else if (arg === "--remote" || arg.startsWith("--remote=")) {
+      const value = arg === "--remote" ? args[++index] : arg.slice("--remote=".length);
+      if (!value || value.startsWith("-"))
+        usageError("--remote requires a remote name");
+      options.remote = value;
+    } else if (arg.startsWith("-"))
+      usageError(`Unknown option: ${arg}`);
+    else
+      positionals.push(arg);
+  }
+  if (options.help)
+    return options;
+  const [subcommand, ...rest] = positionals;
+  options.subcommand = subcommand;
+  if (subcommand === "bind") {
+    const [id, folder, extra] = rest;
+    if (!id)
+      usageError("bind requires a repository id");
+    if (extra !== undefined)
+      usageError(`Unexpected argument: ${extra}`);
+    options.id = id;
+    if (folder)
+      options.folder = folder;
+  } else if (subcommand === "path" || subcommand === "new-identity") {
+    const [folder, extra] = rest;
+    if (extra !== undefined)
+      usageError(`Unexpected argument: ${extra}`);
+    if (folder)
+      options.folder = folder;
+  } else if (subcommand === undefined) {
+    usageError("kennel notes needs a subcommand: path, bind, or new-identity");
+  } else {
+    usageError(`Unknown subcommand: ${subcommand}`);
+  }
+  if (options.replace && subcommand !== "bind")
+    usageError("--replace applies to bind only");
+  if (!options.recordAlias && subcommand !== "bind")
+    usageError("--no-alias applies to bind only");
+  return options;
+}
+async function notes(args) {
+  let options;
+  try {
+    options = parseArgs(args);
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  try {
+    const result = options.subcommand === "bind" ? await bindRepositoryNotes(options.folder, options.id, {
+      recordAlias: options.recordAlias,
+      remote: options.remote,
+      replace: options.replace
+    }) : options.subcommand === "new-identity" ? await newRepositoryIdentity(options.folder, { remote: options.remote }) : await ensureRepositoryNotes(options.folder, { remote: options.remote });
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(`${result.notesDirectory}
+`);
+    if ("aliasOwner" in result && result.aliasOwner) {
+      console.error(`Note: the remote address stays with collection ${result.aliasOwner}; this checkout now uses ${result.id} without an alias.`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(error instanceof RepositoryNotesError ? `Error (${error.code}): ${message}` : `Error: ${message}`);
+    process.exitCode = 1;
+  }
+}
+export {
+  notes
+};