alignfirst 0.4.0 → 0.5.0

package/dist/project-layout.js

@@ -0,0 +1,174 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { type } from "arktype";
+import { CliError } from "./cli-error.js";
+import { errorMessage } from "./errors.js";
+import { gitOutputOrUndefined } from "./git.js";
+export const ITEM_NAMES = [
+    ".alignfirst.json",
+    ".alignfirst.md",
+    "DEVELOPERS.md",
+    "docs",
+    ".plans",
+    "_aligndev",
+];
+const FLAG = "boolean | 'auto'";
+const flagsSchema = type({
+    "+": "reject",
+    ".alignfirst.json?": FLAG,
+    ".alignfirst.md?": FLAG,
+    "DEVELOPERS.md?": FLAG,
+    "docs?": FLAG,
+    ".plans?": FLAG,
+    "_aligndev?": FLAG,
+});
+const companionsSchema = type({
+    "+": "reject",
+    root: "string > 0",
+    paths: type.Record("string", flagsSchema),
+});
+export function layoutOf(ctx) {
+    ctx.layout ??= resolveProjectLayout(ctx.cwd, ctx.home);
+    return ctx.layout;
+}
+export function resolveProjectLayout(cwd, home) {
+    const companion = resolveCompanion(cwd, home);
+    return { companion, locations: resolveLocations(cwd, companion) };
+}
+function resolveCompanion(cwd, home) {
+    const file = readCompanionsFile(home);
+    if (file === undefined)
+        return null;
+    const mainWorktree = findMainWorktree(cwd);
+    if (mainWorktree === undefined)
+        return null;
+    const realHome = realOrResolved(home);
+    const matches = matchingEntries(file, mainWorktree, realHome);
+    if (matches.length === 0)
+        return null;
+    const flags = mergeFlags(matches);
+    assertValidFlags(file, flags, matches);
+    const dir = join(normalizePath(file.root, realHome), companionName(mainWorktree, realHome));
+    return { dir, exists: pathExists(dir), entries: matches.map((match) => match.key), flags };
+}
+function readCompanionsFile(home) {
+    const path = companionsPath(home);
+    if (!pathExists(path))
+        return;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (error) {
+        throw invalidCompanions(path, errorMessage(error));
+    }
+    const file = companionsSchema(value);
+    if (file instanceof type.errors)
+        throw invalidCompanions(path, file.summary.split("\n", 1)[0]);
+    if (!isUserPath(file.root))
+        throw invalidCompanions(path, `root must be an absolute path or start with ~/: ${file.root}`);
+    const badKey = Object.keys(file.paths).find((key) => !isUserPath(key));
+    if (badKey !== undefined)
+        throw invalidCompanions(path, `paths key must be an absolute path or start with ~/: ${badKey}`);
+    return { path, root: file.root, paths: file.paths };
+}
+export function companionsPath(home) {
+    return join(home, ".config", "alignfirst", "companions.json");
+}
+function invalidCompanions(path, detail) {
+    return new CliError(`Invalid ${path}: ${detail}`);
+}
+function isUserPath(value) {
+    return value === "~" || value.startsWith("~/") || isAbsolute(value);
+}
+/** The main worktree is the parent of the common `.git` directory; a bare repository has none. */
+function findMainWorktree(cwd) {
+    const commonDir = gitOutputOrUndefined(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir");
+    if (commonDir === undefined || basename(commonDir) !== ".git")
+        return;
+    return realpathSync(dirname(commonDir));
+}
+function normalizePath(value, realHome) {
+    if (value === "~")
+        return realHome;
+    return realOrResolved(value.startsWith("~/") ? join(realHome, value.slice(2)) : value);
+}
+function realOrResolved(path) {
+    return existsSync(path) ? realpathSync(path) : resolve(path);
+}
+function matchingEntries(file, mainWorktree, realHome) {
+    return Object.entries(file.paths)
+        .map(([key, flags]) => ({ key, path: normalizePath(key, realHome), flags }))
+        .filter((entry) => isSameOrInside(mainWorktree, entry.path))
+        .toSorted((left, right) => right.path.length - left.path.length);
+}
+function isSameOrInside(path, ancestor) {
+    return path === ancestor || path.startsWith(ancestor.endsWith(sep) ? ancestor : ancestor + sep);
+}
+function mergeFlags(matches) {
+    const flagOf = (item) => matches.find((match) => match.flags[item] !== undefined)?.flags[item] ?? "auto";
+    return {
+        ".alignfirst.json": flagOf(".alignfirst.json"),
+        ".alignfirst.md": flagOf(".alignfirst.md"),
+        "DEVELOPERS.md": flagOf("DEVELOPERS.md"),
+        docs: flagOf("docs"),
+        ".plans": flagOf(".plans"),
+        _aligndev: flagOf("_aligndev"),
+    };
+}
+function assertValidFlags(file, flags, matches) {
+    if (flags._aligndev !== true || flags[".plans"] !== "auto")
+        return;
+    const keys = matches.map((match) => match.key).join(", ");
+    throw invalidCompanions(file.path, `"_aligndev": true requires ".plans" set to true or false (matching keys: ${keys})`);
+}
+function companionName(mainWorktree, realHome) {
+    const name = mainWorktree !== realHome && isSameOrInside(mainWorktree, realHome)
+        ? relative(realHome, mainWorktree)
+        : mainWorktree.slice(1);
+    return name.replaceAll("/", "_");
+}
+function resolveLocations(cwd, companion) {
+    const locate = (name) => locateItem(cwd, companion, name);
+    const plans = locate(".plans");
+    return {
+        ".alignfirst.json": locate(".alignfirst.json"),
+        ".alignfirst.md": locate(".alignfirst.md"),
+        "DEVELOPERS.md": locate("DEVELOPERS.md"),
+        docs: locate("docs"),
+        ".plans": plans,
+        _aligndev: companion?.flags._aligndev === true ? companionCopy(companion, ".plans") : plans,
+    };
+}
+function locateItem(cwd, companion, name) {
+    const project = projectCopy(cwd, name);
+    if (companion === null || companion.flags[name] === false)
+        return project;
+    const copy = companionCopy(companion, name);
+    if (companion.flags[name] === true || copy.exists || !project.exists)
+        return copy;
+    return project;
+}
+function projectCopy(cwd, name) {
+    const path = join(cwd, name);
+    return { path, in: "project", exists: pathExists(path) };
+}
+function companionCopy(companion, name) {
+    const path = join(companion.dir, name);
+    return { path, in: "companion", exists: pathExists(path) };
+}
+/** An lstat check, so a broken `.plans` symlink still resolves in place. */
+function pathExists(path) {
+    return lstatSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+/** One line: `<name>: <path> (<in>)`, with `, missing` when absent. */
+export function renderItemLocation(name, location) {
+    return `${name}: ${location.path} (${location.in}${location.exists ? "" : ", missing"})`;
+}
+/** The `_aligndev` tree when it is not the resolved `.plans` and exists. */
+export function separateSessionTree(layout) {
+    const sessions = layout.locations._aligndev;
+    if (!sessions.exists || sessions.path === layout.locations[".plans"].path)
+        return;
+    return sessions.path;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, work files and docs in one command.",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@alignfirst/docmap": "~0.11.0",
+    "@alignfirst/docmap": "~0.11.1",
     "arktype": "^2.2.3",
     "semver": "^7.8.5"
   },
@@ -44,6 +44,6 @@
     "@types/semver": "~7.8.0",
     "rimraf": "~6.1.3",
     "typescript": "~7.0.2",
-    "vitest": "~4.1.11"
+    "vitest": "~5.0.1"
   }
 }

package/templates/guide/core.md

@@ -16,7 +16,7 @@ When the user says there is no ticket or asks for a side ticket, run `{{CMD}} ti
 
 Files use `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`. FILE_PREFIX combines the cycle letter and the file number within that cycle. FILE_NAME includes the prefix and extension.
 
-Immediately before creating each file, run `{{TICKET_CMD}} --next <filename>` with the extension included. It returns TICKET_DIR, CYCLE_LETTER, FILE_NUMBER, and FILE_NAME. Append FILE_NAME to TICKET_DIR to get the file path, preserving the leading dot and existing slash.
+Immediately before creating each file, run `{{TICKET_CMD}} --next <filename>` with the extension included. It returns TICKET_DIR, CYCLE_LETTER, FILE_NUMBER, and FILE_NAME. Append FILE_NAME to TICKET_DIR exactly as printed to get the file path.
 
 With no filename, `{{TICKET_CMD}} --next` returns FILE_PREFIX instead of FILE_NAME. To name several files at once, repeat `--next <filename>` once per file: the command returns FILE_NAMES, numbered in that order. Add `--new-cycle` to any form when the protocol or user calls for a new cycle.