alignfirst 0.8.0 → 0.9.0

package/README.md

@@ -51,20 +51,6 @@ To implement a plan, start a fresh agent context and ask it to execute the plan
 
 AlignFirst stores the work files of a ticket, such as specifications, plans and summaries, in `.plans/<ticket-id>/`. It normally derives the ticket ID from the request or branch and asks when none is available. Files use a cycle letter and sequence number, such as `A1-spec.md` and `A2-plan.md`.
 
-## Global CLI
-
-To type `alignfirst` instead of `npx alignfirst`, install the CLI globally:
-
-```sh
-npm install -g alignfirst
-```
-
-### Update the global CLI
-
-```sh
-npm update -g alignfirst
-```
-
 ## Set up a project (with your agent)
 
 Temporarily install the setup-guide skill:
@@ -95,8 +81,9 @@ Use your alignfirst-setup-guide skill. Set up AlignFirst in this project without
 - `plans` — Link `.plans` to the work-files repository, check the link, archive tickets.
 - `docmap` — Browse project documentation.
 - `conventions` — Print the effective project conventions.
-- `context` — Print the conventions, the project instructions from `.alignfirst.md`, the documentation map when `docs/` exists, and the protocol aliases.
-- `companion add` — Register the current project in the companion registry and create its companion directory.
+- `context` — Print the conventions, the project instructions from `.alignfirst-instructions/context.md`, the documentation map when `docs/` exists, and the protocol aliases.
+- `companion register` — Register the current project in the companion registry. `--create-dir` also creates its companion directory.
+- `companion unregister` — Remove the current project from the companion registry. `--remove-dir` also removes its companion directory.
 - `config` — Report the effective project configuration, the companion directory and the location of each AlignFirst file.
 - `doctor` — Diagnose an AlignFirst setup.
 
@@ -114,23 +101,24 @@ A companion directory holds a project's AlignFirst files outside its repository,
 {
   "paths": {
     "~/projects/team-app": { ".plans": false, "_aligndev": true },
-    "~/projects/client-api": {},
-    "~/projects": {}
+    "~/projects/client-api": {}
   }
 }
 ```
 
-- `paths` — the projects, by absolute or `~/` path. Each value sets flags for the items a companion can hold: `.alignfirst.json`, `.alignfirst.md`, `DEVELOPERS.md`, `docs`, `.plans` and `_aligndev`. A flag is `true`, `false` or `"auto"`.
+- `paths` — the projects, by absolute or `~/` path. Each value sets flags for the items a companion can hold: `.alignfirst.json`, `.alignfirst-instructions`, `DEVELOPERS.md`, `docs`, `.plans` and `_aligndev`. A flag is `true`, `false` or `"auto"`.
 
 An absent registry means no project has a companion. An invalid registry makes every command fail; `doctor` reports it and continues.
 
-Run `alignfirst companion add` in a project to register it. It adds the project's main worktree path with every item on `"auto"`, unless a key already matches it, and creates the companion directory. Set the flags by editing the registry.
+Run `alignfirst companion register` in a project to register it. It adds the project's main worktree path with every item on `"auto"`, unless it is registered. The companion directory is created on the first write, or at once with `--create-dir`. Set the flags by editing the registry.
+
+`alignfirst companion unregister` removes the entry and keeps the directory. With `--remove-dir`, it also removes an empty directory; a non-empty one requires `--force`.
 
 ### Matching
 
-A key matches a project when it names the project's main worktree or one of its ancestors, so every worktree of a project shares one companion. `"~": {}` matches every project under the home directory. For each item, the longest matching key that sets the flag wins, and an unset flag is `"auto"`. A bare repository or a directory outside git has no companion.
+A key matches a project when it names the project's main worktree, so every worktree of a project shares one companion. A key that names another directory matches nothing, and `alignfirst doctor` warns about it. An unset flag is `"auto"`. A bare repository or a directory outside git has no companion.
 
-The companion directory is `~/.alignfirst/companions/<name>`. The name is the main worktree path relative to the home directory, or the absolute path without its leading `/` outside it, with every `/` replaced by `_`. For example, `~/projects/client-api` gets `~/.alignfirst/companions/projects_client-api/`. To keep the companions and their registry elsewhere, make `~/.alignfirst/companions` a symlink.
+The companion directory is `~/.alignfirst/companions/<name>`. The name is the main worktree path relative to the home directory, or the absolute path without its leading `/` outside it, with every `/` replaced by `_`. For example, `~/projects/client-api` gets `~/.alignfirst/companions/projects_client-api/`. Two keys can only share a directory through a `_` in a directory name: `companion register` refuses such a project, and `doctor` warns about it. To keep the companions and their registry elsewhere, make `~/.alignfirst/companions` a symlink.
 
 ### Resolution
 
@@ -146,7 +134,7 @@ The companion directory is `~/.alignfirst/companions/<name>`. The name is the ma
 
 ### Project instructions
 
-`.alignfirst.md` holds free prose for the coding agent: the project instructions a prepared project keeps in its `AGENTS.md`. `alignfirst context` prints it under `# Project Instructions`. It resolves like the other items, so a project copy works too.
+`.alignfirst-instructions/` holds Markdown instructions for the coding agent, one file per moment they apply. `context.md` holds the project instructions a prepared project keeps in its `AGENTS.md`, and `alignfirst context` prints it under `# Project Instructions`. The directory resolves like the other items, so a project copy works too.
 
 ### Agent bootstrap
 

package/dist/cli.js

@@ -68,7 +68,7 @@ Usage:
   ${ctx.form} docmap [<arguments>]
   ${ctx.form} conventions
   ${ctx.form} context
-  ${ctx.form} companion add
+  ${ctx.form} companion register | unregister
   ${ctx.form} config [--json]
   ${ctx.form} doctor
   ${ctx.form} --help

package/dist/commands/companion.js

@@ -1,11 +1,15 @@
+import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
-import { parseBareCommandArgs } from "../parse-args.js";
-import { addCompanion } from "../project-layout.js";
+import { parseCommandArgs } from "../parse-args.js";
+import { registerCompanion, unregisterCompanion } from "../project-layout.js";
+const HELP_OPTION = { help: { type: "boolean", short: "h", default: false } };
 export function runCompanion(ctx, args) {
     const [command, ...rest] = args;
     switch (command) {
-        case "add":
-            return runAdd(ctx, rest);
+        case "register":
+            return runRegister(ctx, rest);
+        case "unregister":
+            return runUnregister(ctx, rest);
         case "--help":
         case "-h":
             ctx.stdout.write(companionUsage(ctx));
@@ -16,21 +20,72 @@ export function runCompanion(ctx, args) {
 }
 function companionUsage(ctx) {
     return `Usage:
-  ${ctx.form} companion add
+  ${ctx.form} companion register [--create-dir]
+  ${ctx.form} companion unregister [--remove-dir [--force]]
 `;
 }
-function runAdd(ctx, args) {
-    const usage = `Usage: ${ctx.form} companion add
+function runRegister(ctx, args) {
+    const usage = `Usage: ${ctx.form} companion register [--create-dir]
 
 Registers the current project in ~/.alignfirst/companions/registry.json, with every item on
-"auto", and creates its companion directory. A project that a key already matches stays as is.
+"auto". A registered project keeps its registration. Fails when another key uses the same
+companion directory.
+
+Options:
+  --create-dir  Create the companion directory when it is missing. Without it, the commands
+                that write an item there create it.
 `;
-    if (parseBareCommandArgs(ctx, args, usage))
+    const { values } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: { "create-dir": { type: "boolean", default: false }, ...HELP_OPTION },
+        strict: true,
+    }));
+    if (printedHelp(ctx, values.help, usage))
         return 0;
-    const registration = addCompanion(ctx.cwd, ctx.home);
+    const registration = registerCompanion(ctx.cwd, ctx.home, { createDir: values["create-dir"] });
     ctx.stdout.write(registration.added
         ? `Registered ${registration.key} in ${registration.registry}.\n`
         : `Already registered by ${registration.key} in ${registration.registry}.\n`);
-    ctx.stdout.write(`Companion: ${registration.dir}\n`);
+    const state = registration.created ? " (created)" : registration.exists ? "" : " (missing)";
+    ctx.stdout.write(`Companion: ${registration.dir}${state}\n`);
+    ctx.stdout.write(`Next: write the items at the paths \`${ctx.form} config\` reports.\n`);
+    return 0;
+}
+function runUnregister(ctx, args) {
+    const usage = `Usage: ${ctx.form} companion unregister [--remove-dir [--force]]
+
+Removes the current project from ~/.alignfirst/companions/registry.json. Keeps its companion
+directory, unless --remove-dir.
+
+Options:
+  --remove-dir  Also remove the companion directory. Fails, with no change, when it is not
+                empty or another key uses it.
+  --force       With --remove-dir, delete a non-empty companion directory.
+`;
+    const { values } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: {
+            "remove-dir": { type: "boolean", default: false },
+            force: { type: "boolean", default: false },
+            ...HELP_OPTION,
+        },
+        strict: true,
+    }));
+    if (printedHelp(ctx, values.help, usage))
+        return 0;
+    const { "remove-dir": removeDir, force } = values;
+    if (force && !removeDir)
+        throw new CliError(`--force requires --remove-dir.\n\n${usage}`);
+    const removal = unregisterCompanion(ctx.cwd, ctx.home, { removeDir, force });
+    ctx.stdout.write(`Unregistered ${removal.key} from ${removal.registry}.\n`);
+    if (removal.removed)
+        ctx.stdout.write(`Removed companion directory: ${removal.dir}\n`);
+    else if (removal.empty !== undefined)
+        ctx.stdout.write(`Orphaned companion directory: ${removal.dir}${removal.empty ? " (empty)" : ""}\n`);
     return 0;
 }
+function printedHelp(ctx, help, usage) {
+    if (help)
+        ctx.stdout.write(usage);
+    return help;
+}

package/dist/commands/context.js

@@ -1,4 +1,5 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { CliError } from "../cli-error.js";
 import { renderCommandForm } from "../command-form.js";
 import { renderConventions } from "../conventions.js";
@@ -17,10 +18,10 @@ export function runContext(ctx, args) {
     return code;
 }
 function writeProjectInstructions(ctx) {
-    const location = layoutOf(ctx).locations[".alignfirst.md"];
-    if (!location.exists)
+    const path = join(layoutOf(ctx).locations[".alignfirst-instructions"].path, "context.md");
+    if (!existsSync(path))
         return;
-    const content = readInstructions(location.path).trim();
+    const content = readInstructions(path).trim();
     if (content === "")
         return;
     ctx.stdout.write(`\n# Project Instructions\n\n${content}\n`);

package/dist/commands/doctor.js

@@ -8,7 +8,7 @@ import { parseBareCommandArgs } from "../parse-args.js";
 import { resolvePlansMode } from "../plans/mode.js";
 import { findStoppedRebase } from "../plans/rebase.js";
 import { PROJECT_CONFIG_FILENAME, resolveProjectConfig, } from "../project-config.js";
-import { registryPath, ITEM_NAMES, layoutOf, renderItemLocation, } from "../project-layout.js";
+import { registryPath, sharedCompanionDirs, strayRegistryKeys, ITEM_NAMES, layoutOf, renderItemLocation, } from "../project-layout.js";
 import { COMMAND_SKILLS, findInstalledSkill } from "../skills.js";
 import { cliRangeResult } from "../version-guard.js";
 export function runDoctor(ctx, args) {
@@ -73,16 +73,27 @@ function inspectCompanion(ctx) {
         level: "ok",
         text: `registry ${existsSync(path) ? "valid" : "absent"} (${path})`,
     };
+    const registryLines = [
+        file,
+        ...strayRegistryKeys(ctx.home).map(describeStrayKey),
+        ...sharedCompanionDirs(ctx.home).map(describeSharedDir),
+    ];
     if (layout.companion === null)
-        return [file, { level: "ok", text: "none" }];
+        return [...registryLines, { level: "ok", text: "none" }];
     const { companion } = layout;
     return [
-        file,
-        { level: "ok", text: `matched by ${companion.entries.join(", ")}` },
+        ...registryLines,
+        { level: "ok", text: `key ${companion.key}` },
         { level: "ok", text: `directory ${companion.dir}${companion.exists ? "" : " (missing)"}` },
         ...ITEM_NAMES.map((name) => describeItem(name, layout, companion)),
     ];
 }
+function describeStrayKey(key) {
+    return { level: "warn", text: `key ${key} names no git main worktree (ignored)` };
+}
+function describeSharedDir({ dir, keys }) {
+    return { level: "warn", text: `keys ${keys.join(", ")} share the companion directory ${dir}` };
+}
 function describeItem(name, layout, companion) {
     const location = layout.locations[name];
     const missingCopy = companion.flags[name] === true && !location.exists;

package/dist/project-layout.d.ts

@@ -1,5 +1,5 @@
 import type { CommandContext } from "./context.js";
-export declare const ITEM_NAMES: readonly [".alignfirst.json", ".alignfirst.md", "DEVELOPERS.md", "docs", ".plans", "_aligndev"];
+export declare const ITEM_NAMES: readonly [".alignfirst.json", ".alignfirst-instructions", "DEVELOPERS.md", "docs", ".plans", "_aligndev"];
 export type ItemName = (typeof ITEM_NAMES)[number];
 export type Flag = boolean | "auto";
 export interface ProjectLayout {
@@ -10,8 +10,8 @@ export interface CompanionLayout {
     /** Absolute. */
     dir: string;
     exists: boolean;
-    /** Matching keys as written, most specific first. */
-    entries: string[];
+    /** The registry key, as written. */
+    key: string;
     /** Effective flags. */
     flags: Record<ItemName, Flag>;
 }
@@ -30,14 +30,42 @@ export declare function renderItemLocation(name: ItemName, location: ItemLocatio
 export declare function separateSessionTree(layout: ProjectLayout): string | undefined;
 export interface CompanionRegistration {
     registry: string;
-    /** The key added, or the most specific key that already matched. */
+    /** The key added, or the key already present. */
     key: string;
     added: boolean;
     /** Absolute. */
     dir: string;
+    exists: boolean;
+    created: boolean;
+}
+/**
+ * Registers the main worktree of `cwd` with every item on `"auto"`, unless it is registered.
+ * Creates the registry when it is missing, and the companion directory with `createDir`.
+ */
+export declare function registerCompanion(cwd: string, home: string, { createDir }: {
+    createDir: boolean;
+}): CompanionRegistration;
+export interface CompanionUnregistration {
+    registry: string;
+    key: string;
+    /** Absolute. */
+    dir: string;
+    /** `undefined` when the directory is missing. */
+    empty?: boolean;
+    removed: boolean;
 }
 /**
- * Registers the main worktree of `cwd` with every item on `"auto"`, unless a key already matches
- * it, and creates its companion directory. Creates the registry when it is missing.
+ * Removes the registry key of the main worktree of `cwd`. With `removeDir`, also removes its
+ * companion directory: a non-empty one requires `force`. Fails before any change.
  */
-export declare function addCompanion(cwd: string, home: string): CompanionRegistration;
+export declare function unregisterCompanion(cwd: string, home: string, { removeDir, force }: {
+    removeDir: boolean;
+    force: boolean;
+}): CompanionUnregistration;
+/** The registry keys that name no git main worktree: they match nothing. */
+export declare function strayRegistryKeys(home: string): string[];
+/** The companion directories shared by several registry keys, with those keys. */
+export declare function sharedCompanionDirs(home: string): {
+    dir: string;
+    keys: string[];
+}[];

package/dist/project-layout.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { type } from "arktype";
 import { CliError } from "./cli-error.js";
@@ -6,7 +6,7 @@ import { errorMessage } from "./errors.js";
 import { gitOutputOrUndefined } from "./git.js";
 export const ITEM_NAMES = [
     ".alignfirst.json",
-    ".alignfirst.md",
+    ".alignfirst-instructions",
     "DEVELOPERS.md",
     "docs",
     ".plans",
@@ -19,7 +19,7 @@ const FLAG = "boolean | 'auto'";
 const flagsSchema = type({
     "+": "reject",
     ".alignfirst.json?": FLAG,
-    ".alignfirst.md?": FLAG,
+    ".alignfirst-instructions?": FLAG,
     "DEVELOPERS.md?": FLAG,
     "docs?": FLAG,
     ".plans?": FLAG,
@@ -45,13 +45,13 @@ function resolveCompanion(cwd, home) {
     if (mainWorktree === undefined)
         return null;
     const realHome = realOrResolved(home);
-    const matches = matchingEntries(registry, mainWorktree, realHome);
-    if (matches.length === 0)
+    const entry = findEntry(registry, mainWorktree, realHome);
+    if (entry === undefined)
         return null;
-    const flags = mergeFlags(matches);
-    assertValidFlags(registry, flags, matches);
+    const flags = effectiveFlags(entry);
+    assertValidFlags(registry, flags, entry);
     const dir = companionDir(mainWorktree, realHome);
-    return { dir, exists: pathExists(dir), entries: matches.map((match) => match.key), flags };
+    return { dir, exists: pathExists(dir), key: entry.key, flags };
 }
 function readRegistry(home) {
     const path = registryPath(home);
@@ -96,31 +96,28 @@ function normalizePath(value, realHome) {
 function realOrResolved(path) {
     return existsSync(path) ? realpathSync(path) : resolve(path);
 }
-function matchingEntries(registry, mainWorktree, realHome) {
-    return Object.entries(registry.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 findEntry(registry, mainWorktree, realHome) {
+    const key = Object.keys(registry.paths).find((candidate) => normalizePath(candidate, realHome) === mainWorktree);
+    return key === undefined ? undefined : { key, flags: registry.paths[key] };
 }
 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";
+function effectiveFlags(entry) {
+    const flagOf = (item) => entry.flags[item] ?? "auto";
     return {
         ".alignfirst.json": flagOf(".alignfirst.json"),
-        ".alignfirst.md": flagOf(".alignfirst.md"),
+        ".alignfirst-instructions": flagOf(".alignfirst-instructions"),
         "DEVELOPERS.md": flagOf("DEVELOPERS.md"),
         docs: flagOf("docs"),
         ".plans": flagOf(".plans"),
         _aligndev: flagOf("_aligndev"),
     };
 }
-function assertValidFlags(registry, flags, matches) {
+function assertValidFlags(registry, flags, entry) {
     if (flags._aligndev !== true || flags[".plans"] !== "auto")
         return;
-    const keys = matches.map((match) => match.key).join(", ");
-    throw invalidRegistry(registry.path, `"_aligndev": true requires ".plans" set to true or false (matching keys: ${keys})`);
+    throw invalidRegistry(registry.path, `"_aligndev": true requires ".plans" set to true or false (key: ${entry.key})`);
 }
 function companionDir(mainWorktree, realHome) {
     return join(normalizePath(COMPANIONS_ROOT, realHome), companionName(mainWorktree, realHome));
@@ -136,7 +133,7 @@ function resolveLocations(cwd, companion) {
     const plans = locate(".plans");
     return {
         ".alignfirst.json": locate(".alignfirst.json"),
-        ".alignfirst.md": locate(".alignfirst.md"),
+        ".alignfirst-instructions": locate(".alignfirst-instructions"),
         "DEVELOPERS.md": locate("DEVELOPERS.md"),
         docs: locate("docs"),
         ".plans": plans,
@@ -176,32 +173,111 @@ export function separateSessionTree(layout) {
     return sessions.path;
 }
 /**
- * Registers the main worktree of `cwd` with every item on `"auto"`, unless a key already matches
- * it, and creates its companion directory. Creates the registry when it is missing.
+ * Registers the main worktree of `cwd` with every item on `"auto"`, unless it is registered.
+ * Creates the registry when it is missing, and the companion directory with `createDir`.
  */
-export function addCompanion(cwd, home) {
-    const mainWorktree = findMainWorktree(cwd);
-    if (mainWorktree === undefined)
-        throw new CliError("A companion needs a git repository with a main worktree.");
+export function registerCompanion(cwd, home, { createDir }) {
+    const mainWorktree = requireMainWorktree(cwd);
     const realHome = realOrResolved(home);
     const registry = readRegistry(home) ?? { path: registryPath(home), paths: {} };
-    const match = matchingEntries(registry, mainWorktree, realHome)[0];
-    const key = match?.key ?? userPathOf(mainWorktree, realHome);
-    if (match === undefined)
-        writeRegistry(registry, key);
+    const entry = findEntry(registry, mainWorktree, realHome);
+    const key = entry?.key ?? userPathOf(mainWorktree, realHome);
     const dir = companionDir(mainWorktree, realHome);
-    mkdirSync(dir, { recursive: true });
-    return { registry: registry.path, key, added: match === undefined, dir };
+    if (entry === undefined) {
+        assertOwnCompanionDir(registry, key, dir, realHome);
+        writeRegistry(registry.path, { ...registry.paths, [key]: {} });
+    }
+    const created = createDir && !pathExists(dir);
+    if (created)
+        mkdirSync(dir, { recursive: true });
+    return {
+        registry: registry.path,
+        key,
+        added: entry === undefined,
+        dir,
+        exists: pathExists(dir),
+        created,
+    };
+}
+function requireMainWorktree(cwd) {
+    const mainWorktree = findMainWorktree(cwd);
+    if (mainWorktree === undefined)
+        throw new CliError("A companion needs a git repository with a main worktree.");
+    return mainWorktree;
 }
 function userPathOf(path, realHome) {
     if (path === realHome)
         return "~";
     return isSameOrInside(path, realHome) ? `~/${relative(realHome, path)}` : path;
 }
-function writeRegistry(registry, key) {
-    mkdirSync(dirname(registry.path), { recursive: true });
-    const paths = { ...registry.paths, [key]: {} };
-    const tmpPath = `${registry.path}.${process.pid}.tmp`;
+/** Two keys collide when their names differ only by a `_` in place of a `/`. */
+function assertOwnCompanionDir(registry, key, dir, realHome) {
+    const others = (keysByCompanionDir(registry, realHome).get(dir) ?? []).filter((k) => k !== key);
+    if (others.length === 0)
+        return;
+    throw new CliError(`The companion directory ${dir} is already used by ${others.join(", ")}.`);
+}
+function keysByCompanionDir(registry, realHome) {
+    const keysByDir = new Map();
+    for (const key of Object.keys(registry.paths)) {
+        const dir = companionDir(normalizePath(key, realHome), realHome);
+        keysByDir.set(dir, [...(keysByDir.get(dir) ?? []), key]);
+    }
+    return keysByDir;
+}
+function writeRegistry(path, paths) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmpPath = `${path}.${process.pid}.tmp`;
     writeFileSync(tmpPath, `${JSON.stringify({ paths }, undefined, 2)}\n`);
-    renameSync(tmpPath, registry.path);
+    renameSync(tmpPath, path);
+}
+/**
+ * Removes the registry key of the main worktree of `cwd`. With `removeDir`, also removes its
+ * companion directory: a non-empty one requires `force`. Fails before any change.
+ */
+export function unregisterCompanion(cwd, home, { removeDir, force }) {
+    const mainWorktree = requireMainWorktree(cwd);
+    const realHome = realOrResolved(home);
+    const path = registryPath(home);
+    const registry = readRegistry(home);
+    const entry = registry && findEntry(registry, mainWorktree, realHome);
+    if (!registry || entry === undefined)
+        throw new CliError(`${mainWorktree} is not registered in ${path}.`);
+    const dir = companionDir(mainWorktree, realHome);
+    const entries = pathExists(dir) ? readdirSync(dir) : undefined;
+    if (removeDir)
+        assertRemovableDir(registry, entry.key, dir, entries, force, realHome);
+    const { [entry.key]: _removed, ...paths } = registry.paths;
+    writeRegistry(path, paths);
+    const removed = removeDir && entries !== undefined;
+    if (removed)
+        rmSync(dir, { recursive: true, force: true });
+    return { registry: path, key: entry.key, dir, empty: entries && entries.length === 0, removed };
+}
+function assertRemovableDir(registry, key, dir, entries, force, realHome) {
+    assertOwnCompanionDir(registry, key, dir, realHome);
+    if (force || entries === undefined || entries.length === 0)
+        return;
+    throw new CliError(`The companion directory ${dir} is not empty: ${entries.sort().join(", ")}. ` +
+        "Add --force to delete it.");
+}
+/** The registry keys that name no git main worktree: they match nothing. */
+export function strayRegistryKeys(home) {
+    const registry = readRegistry(home);
+    if (registry === undefined)
+        return [];
+    const realHome = realOrResolved(home);
+    return Object.keys(registry.paths).filter((key) => {
+        const path = normalizePath(key, realHome);
+        return !existsSync(path) || findMainWorktree(path) !== path;
+    });
+}
+/** The companion directories shared by several registry keys, with those keys. */
+export function sharedCompanionDirs(home) {
+    const registry = readRegistry(home);
+    if (registry === undefined)
+        return [];
+    return [...keysByCompanionDir(registry, realOrResolved(home))]
+        .filter(([, keys]) => keys.length > 1)
+        .map(([dir, keys]) => ({ dir, keys }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, work files and docs in one command.",