alignfirst 0.8.0 → 0.10.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,14 +134,14 @@ 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
 
 An agent reads a repository's `AGENTS.md` on its own, but never a companion. When your repositories carry no AlignFirst instructions, add this line to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
 
 ```text
-In a git repository, run `alignfirst context` as your first command, whatever the task, unless the project's instructions already say so.
+In a git repository, run `npx -y alignfirst context` as your first command, whatever the task, unless the project's instructions already say so.
 ```
 
 ## Upgrade from v1, v2, or v3

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

@@ -1,16 +1,16 @@
 import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import semver from "semver";
 import { resolveDefaultBranch } from "../default-branch.js";
 import { errorMessage } from "../errors.js";
 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";
+import { isAheadOfRange } from "../version-range.js";
 export function runDoctor(ctx, args) {
     const usage = `Usage: ${ctx.form} doctor\n`;
     if (parseBareCommandArgs(ctx, args, usage))
@@ -62,7 +62,7 @@ function inspectConfig(ctx, resolved) {
         level: result.satisfied ? "ok" : "error",
         text: `${result.satisfied ? "satisfies" : "does not satisfy"} ${result.range}`,
     });
-    if (semver.gtr(ctx.version, result.range))
+    if (isAheadOfRange(ctx.version, result.range))
         lines.push({ level: "warn", text: `${ctx.version} is ahead of ${result.range}` });
     return lines;
 }
@@ -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;
@@ -143,11 +154,17 @@ function describeCommandSkill({ name, installed }) {
 }
 function describeInstalledSkill(name, installed) {
     const version = installed.version ?? "unknown";
-    const parsed = semver.parse(installed.version);
-    if (parsed === null || parsed.major < 4)
+    const major = majorOf(installed.version);
+    if (major === undefined || major < 4)
         return {
             level: "warn",
             text: `${name} ${version} predates v4; update: npx -y skills update --global --yes`,
         };
     return { level: "ok", text: `${name} ${version} (${installed.root})` };
 }
+function majorOf(version) {
+    if (version === undefined)
+        return;
+    const match = /^(\d+)\./.exec(version);
+    return match === null ? undefined : Number(match[1]);
+}

package/dist/json-shape.d.ts

@@ -0,0 +1,19 @@
+export type Check<T> = (value: unknown, path: string) => T;
+export interface OptionalField<T> {
+    optional: Check<T>;
+}
+type Fields<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? OptionalField<Exclude<T[K], undefined>> : Check<T[K]>;
+};
+/** Runs `check` at the root; a shape failure becomes `toError(<message>)`. */
+export declare function parseShape<T>(check: Check<T>, value: unknown, toError: (detail: string) => Error): T;
+/** Rejects the first unknown key, then checks each field in declaration order. */
+export declare function object<T extends object>(fields: Fields<T>): Check<T>;
+export declare function shapeError(path: string, expectation: string): Error;
+export declare function optional<T>(check: Check<T>): OptionalField<T>;
+export declare function record<T>(check: Check<T>): Check<Record<string, T>>;
+export declare function literal<const T extends readonly (string | number)[]>(...values: T): Check<T[number]>;
+export declare function integerBetween(min: number, max: number): Check<number>;
+export declare function nonEmptyString(value: unknown, path: string): string;
+export declare function boolean(value: unknown, path: string): boolean;
+export {};

package/dist/json-shape.js

@@ -0,0 +1,93 @@
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+class ShapeError extends Error {
+}
+/** Runs `check` at the root; a shape failure becomes `toError(<message>)`. */
+export function parseShape(check, value, toError) {
+    try {
+        return check(value, "");
+    }
+    catch (error) {
+        if (error instanceof ShapeError)
+            throw toError(error.message);
+        throw error;
+    }
+}
+/** Rejects the first unknown key, then checks each field in declaration order. */
+export function object(fields) {
+    const entries = Object.entries(fields);
+    return (value, path) => {
+        if (!isPlainObject(value))
+            throw shapeError(path, "be an object");
+        const unknownKey = Object.keys(value).find((key) => !Object.hasOwn(fields, key));
+        if (unknownKey !== undefined)
+            throw shapeError(childPath(path, unknownKey), "be removed");
+        const result = {};
+        for (const [key, field] of entries) {
+            const fieldPath = childPath(path, key);
+            if (typeof field === "function")
+                result[key] = field(value[key], fieldPath);
+            else if (value[key] !== undefined)
+                result[key] = field.optional(value[key], fieldPath);
+        }
+        // The fields mirror T key by key.
+        return result;
+    };
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function childPath(path, key) {
+    if (!IDENTIFIER.test(key))
+        return bracketPath(path, JSON.stringify(key));
+    return path === "" ? key : `${path}.${key}`;
+}
+function bracketPath(path, segment) {
+    return `${path === "" ? "value" : path}[${segment}]`;
+}
+export function shapeError(path, expectation) {
+    return new ShapeError(`${path === "" ? "value" : path} must ${expectation}`);
+}
+export function optional(check) {
+    return { optional: check };
+}
+export function record(check) {
+    return (value, path) => {
+        if (!isPlainObject(value))
+            throw shapeError(path, "be an object");
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, check(item, childPath(path, key))]));
+    };
+}
+export function literal(...values) {
+    const expectation = `be ${listOf(values.map((item) => JSON.stringify(item)))}`;
+    return (value, path) => {
+        const match = values.find((item) => item === value);
+        if (match === undefined)
+            throw shapeError(path, expectation);
+        return match;
+    };
+}
+function listOf(items) {
+    if (items.length === 1)
+        return items[0];
+    return `${items.slice(0, -1).join(", ")} or ${items.at(-1)}`;
+}
+export function integerBetween(min, max) {
+    return (value, path) => {
+        if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max)
+            throw shapeError(path, `be an integer from ${min} to ${max}`);
+        return value;
+    };
+}
+export function nonEmptyString(value, path) {
+    if (typeof value !== "string" || value.length === 0)
+        throw shapeError(path, "be a non-empty string");
+    return value;
+}
+export function boolean(value, path) {
+    if (typeof value !== "boolean")
+        throw shapeError(path, "be a boolean");
+    return value;
+}

package/dist/project-config.js

@@ -1,39 +1,34 @@
 import { readFileSync } from "node:fs";
-import { type } from "arktype";
-import semver from "semver";
 import { CliError } from "./cli-error.js";
 import { errorMessage } from "./errors.js";
+import { boolean, integerBetween, literal, nonEmptyString, object, optional, parseShape, } from "./json-shape.js";
+import { isValidVersionRange } from "./version-range.js";
 export const PROJECT_CONFIG_FILENAME = ".alignfirst.json";
-const portRangeSchema = type({
-    "+": "reject",
-    first: "1 <= number.integer <= 65535",
-    last: "1 <= number.integer <= 65535",
+const portRangeShape = object({
+    first: integerBetween(1, 65_535),
+    last: integerBetween(1, 65_535),
 });
-const plansSchema = type({
-    "+": "reject",
-    "folder?": "string > 0",
-    "autoArchive?": "boolean",
+const plansShape = object({
+    folder: optional(nonEmptyString),
+    autoArchive: optional(boolean),
 });
-const commitSchema = type({
-    "+": "reject",
-    style: "'conventionalCommit'",
-    "ticketReference?": "'bracketed' | 'bracketedHash'",
+const commitShape = object({
+    style: literal("conventionalCommit"),
+    ticketReference: optional(literal("bracketed", "bracketedHash")),
 });
-const gitSchema = type({
-    "+": "reject",
-    "defaultBranch?": "string > 0",
-    "branchNameTemplate?": "string > 0",
-    "commit?": commitSchema,
-    "agentCoauthoring?": "boolean",
+const gitShape = object({
+    defaultBranch: optional(nonEmptyString),
+    branchNameTemplate: optional(nonEmptyString),
+    commit: optional(commitShape),
+    agentCoauthoring: optional(boolean),
 });
-const projectConfigSchema = type({
-    "+": "reject",
-    schemaVersion: "1",
-    "cli?": "string > 0",
-    "ticketIdPattern?": "string > 0",
-    "plans?": plansSchema,
-    "portRange?": portRangeSchema,
-    "git?": gitSchema,
+const projectConfigShape = object({
+    schemaVersion: literal(1),
+    cli: optional(nonEmptyString),
+    ticketIdPattern: optional(nonEmptyString),
+    plans: optional(plansShape),
+    portRange: optional(portRangeShape),
+    git: optional(gitShape),
 });
 export function resolveProjectConfig(layout) {
     const location = layout.locations[PROJECT_CONFIG_FILENAME];
@@ -52,11 +47,9 @@ export function readProjectConfig(path) {
     return validateProjectConfig(value, path);
 }
 export function validateProjectConfig(value, label) {
-    const config = projectConfigSchema(value);
-    if (config instanceof type.errors)
-        throw invalidConfig(label, config.summary.split("\n", 1)[0]);
-    if (config.cli !== undefined && semver.validRange(config.cli) === null)
-        throw invalidConfig(label, `cli is not a valid semver range: ${config.cli}`);
+    const config = parseShape(projectConfigShape, value, (detail) => invalidConfig(label, detail));
+    if (config.cli !== undefined && !isValidVersionRange(config.cli))
+        throw invalidConfig(label, `cli is not a supported version range: ${config.cli}`);
     if (config.ticketIdPattern !== undefined)
         assertValidPattern(config.ticketIdPattern, label);
     if (config.portRange !== undefined)

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,12 +1,12 @@
-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";
 import { errorMessage } from "./errors.js";
 import { gitOutputOrUndefined } from "./git.js";
+import { object, optional, parseShape, record, shapeError } from "./json-shape.js";
 export const ITEM_NAMES = [
     ".alignfirst.json",
-    ".alignfirst.md",
+    ".alignfirst-instructions",
     "DEVELOPERS.md",
     "docs",
     ".plans",
@@ -15,20 +15,15 @@ export const ITEM_NAMES = [
 // The directory holding the companions and their registry. A symlink there moves them elsewhere.
 const COMPANIONS_ROOT = "~/.alignfirst/companions";
 const REGISTRY_FILE = "registry.json";
-const FLAG = "boolean | 'auto'";
-const flagsSchema = type({
-    "+": "reject",
-    ".alignfirst.json?": FLAG,
-    ".alignfirst.md?": FLAG,
-    "DEVELOPERS.md?": FLAG,
-    "docs?": FLAG,
-    ".plans?": FLAG,
-    "_aligndev?": FLAG,
-});
-const registrySchema = type({
-    "+": "reject",
-    paths: type.Record("string", flagsSchema),
+const flagsShape = object({
+    ".alignfirst.json": optional(flag),
+    ".alignfirst-instructions": optional(flag),
+    "DEVELOPERS.md": optional(flag),
+    docs: optional(flag),
+    ".plans": optional(flag),
+    _aligndev: optional(flag),
 });
+const registryFileShape = object({ paths: record(flagsShape) });
 export function layoutOf(ctx) {
     ctx.layout ??= resolveProjectLayout(ctx.cwd, ctx.home);
     return ctx.layout;
@@ -45,13 +40,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);
@@ -64,9 +59,7 @@ function readRegistry(home) {
     catch (error) {
         throw invalidRegistry(path, errorMessage(error));
     }
-    const file = registrySchema(value);
-    if (file instanceof type.errors)
-        throw invalidRegistry(path, file.summary.split("\n", 1)[0]);
+    const file = parseShape(registryFileShape, value, (detail) => invalidRegistry(path, detail));
     const badKey = Object.keys(file.paths).find((key) => !isUserPath(key));
     if (badKey !== undefined)
         throw invalidRegistry(path, `paths key must be an absolute path or start with ~/: ${badKey}`);
@@ -78,6 +71,11 @@ export function registryPath(home) {
 function invalidRegistry(path, detail) {
     return new CliError(`Invalid ${path}: ${detail}`);
 }
+function flag(value, path) {
+    if (typeof value !== "boolean" && value !== "auto")
+        throw shapeError(path, 'be a boolean or "auto"');
+    return value;
+}
 function isUserPath(value) {
     return value === "~" || value.startsWith("~/") || isAbsolute(value);
 }
@@ -96,31 +94,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 +131,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 +171,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/dist/version-guard.js

@@ -1,5 +1,5 @@
-import semver from "semver";
 import { CliError } from "./cli-error.js";
+import { satisfiesRange } from "./version-range.js";
 export function checkCliRange(config, installedVersion, commandArgs) {
     const result = cliRangeResult(config, installedVersion);
     if (result === undefined || result.satisfied)
@@ -13,5 +13,5 @@ export function cliRangeResult(config, installedVersion) {
     const range = config?.cli;
     if (range === undefined)
         return;
-    return { range, satisfied: semver.satisfies(installedVersion, range) };
+    return { range, satisfied: satisfiesRange(installedVersion, range) };
 }

package/dist/version-range.d.ts

@@ -0,0 +1,5 @@
+export declare function isValidVersionRange(range: string): boolean;
+/** False for a version with a prerelease tag or an invalid range. */
+export declare function satisfiesRange(version: string, range: string): boolean;
+/** True when `version` is above every version the range accepts. */
+export declare function isAheadOfRange(version: string, range: string): boolean;

package/dist/version-range.js

@@ -0,0 +1,103 @@
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+// Two-character operators first, so `<=` is not read as `<`.
+const OPERATORS = ["<=", ">=", "<", ">", "=", "~", "^"];
+export function isValidVersionRange(range) {
+    return parseRange(range) !== undefined;
+}
+/** False for a version with a prerelease tag or an invalid range. */
+export function satisfiesRange(version, range) {
+    const parsed = parseVersion(version);
+    const sets = parseRange(range);
+    if (parsed === undefined || sets === undefined)
+        return false;
+    return sets.some((set) => set.every((comparator) => holds(comparator, parsed)));
+}
+/** True when `version` is above every version the range accepts. */
+export function isAheadOfRange(version, range) {
+    const parsed = parseVersion(version);
+    const sets = parseRange(range);
+    if (parsed === undefined || sets === undefined)
+        return false;
+    return sets.every((set) => set.some((comparator) => exceeds(comparator, parsed)));
+}
+function parseVersion(text) {
+    const match = VERSION.exec(text);
+    if (match === null)
+        return;
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+function parseRange(range) {
+    const sets = [];
+    for (const part of range.split("||")) {
+        const set = parseComparatorSet(part.trim());
+        if (set === undefined)
+            return;
+        sets.push(set);
+    }
+    return sets;
+}
+function parseComparatorSet(text) {
+    if (text === "")
+        return;
+    const comparators = [];
+    for (const token of text.split(/\s+/)) {
+        const desugared = parseComparator(token);
+        if (desugared === undefined)
+            return;
+        comparators.push(...desugared);
+    }
+    return comparators;
+}
+function parseComparator(token) {
+    const operator = OPERATORS.find((candidate) => token.startsWith(candidate));
+    const version = parseVersion(operator === undefined ? token : token.slice(operator.length));
+    if (version === undefined)
+        return;
+    return desugar(operator ?? "=", version);
+}
+function desugar(operator, version) {
+    if (operator === "~") {
+        const upper = { major: version.major, minor: version.minor + 1, patch: 0 };
+        return [lowerBound(version), { operator: "<", version: upper }];
+    }
+    if (operator === "^")
+        return [lowerBound(version), { operator: "<", version: caretUpper(version) }];
+    return [{ operator, version }];
+}
+function lowerBound(version) {
+    return { operator: ">=", version };
+}
+function caretUpper({ major, minor, patch }) {
+    if (major > 0)
+        return { major: major + 1, minor: 0, patch: 0 };
+    if (minor > 0)
+        return { major: 0, minor: minor + 1, patch: 0 };
+    return { major: 0, minor: 0, patch: patch + 1 };
+}
+function holds({ operator, version }, candidate) {
+    const order = compareVersions(candidate, version);
+    switch (operator) {
+        case "<":
+            return order < 0;
+        case "<=":
+            return order <= 0;
+        case ">":
+            return order > 0;
+        case ">=":
+            return order >= 0;
+        case "=":
+            return order === 0;
+    }
+}
+function compareVersions(left, right) {
+    return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+}
+/** A set is exceeded when the candidate fails one of its upper bounds on the high side. */
+function exceeds({ operator, version }, candidate) {
+    const order = compareVersions(candidate, version);
+    if (operator === "<")
+        return order >= 0;
+    if (operator === "<=" || operator === "=")
+        return order > 0;
+    return false;
+}

package/package.json

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