alignfirst 0.6.0 → 0.7.0

package/README.md

@@ -96,6 +96,7 @@ Use your alignfirst-setup-guide skill. Set up AlignFirst in this project without
 - `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.
 - `config` — Report the effective project configuration, the companion directory and the location of each AlignFirst file.
 - `doctor` — Diagnose an AlignFirst setup.
 
@@ -107,7 +108,7 @@ Run `alignfirst --help` for command usage or `alignfirst guide` to choose a prot
 
 ## Companion directories
 
-A companion directory holds a project's AlignFirst files outside its repository, so the repository stays untouched. `~/.alignfirst/companions.json` declares which projects have one:
+A companion directory holds a project's AlignFirst files outside its repository, so the repository stays untouched. The companion registry, `~/.alignfirst/companions/registry.json`, declares which projects have one:
 
 ```json
 {
@@ -121,13 +122,15 @@ A companion directory holds a project's AlignFirst files outside its repository,
 
 - `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"`.
 
-An absent file means no project has a companion. An invalid file makes every command fail; `doctor` reports it and continues.
+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.
 
 ### 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.
 
-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 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/`. To keep the companions and their registry elsewhere, make `~/.alignfirst/companions` a symlink.
 
 ### Resolution
 

package/dist/cli.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { CliError } from "./cli-error.js";
 import { resolveCommandForm } from "./command-form.js";
+import { runCompanion } from "./commands/companion.js";
 import { runConfig } from "./commands/config.js";
 import { runContext } from "./commands/context.js";
 import { runConventions } from "./commands/conventions.js";
@@ -67,6 +68,7 @@ Usage:
   ${ctx.form} docmap [<arguments>]
   ${ctx.form} conventions
   ${ctx.form} context
+  ${ctx.form} companion add
   ${ctx.form} config [--json]
   ${ctx.form} doctor
   ${ctx.form} --help
@@ -89,6 +91,8 @@ function dispatch(ctx, command, args) {
             return runConventions(ctx, args);
         case "context":
             return runContext(ctx, args);
+        case "companion":
+            return runCompanion(ctx, args);
         case "config":
             return runConfig(ctx, args);
         case "doctor":

package/dist/commands/companion.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../context.js";
+export declare function runCompanion(ctx: CommandContext, args: string[]): number;

package/dist/commands/companion.js

@@ -0,0 +1,36 @@
+import { CliError } from "../cli-error.js";
+import { parseBareCommandArgs } from "../parse-args.js";
+import { addCompanion } from "../project-layout.js";
+export function runCompanion(ctx, args) {
+    const [command, ...rest] = args;
+    switch (command) {
+        case "add":
+            return runAdd(ctx, rest);
+        case "--help":
+        case "-h":
+            ctx.stdout.write(companionUsage(ctx));
+            return 0;
+        default:
+            throw new CliError(`Unknown or missing companion command.\n\n${companionUsage(ctx)}`);
+    }
+}
+function companionUsage(ctx) {
+    return `Usage:
+  ${ctx.form} companion add
+`;
+}
+function runAdd(ctx, args) {
+    const usage = `Usage: ${ctx.form} companion add
+
+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.
+`;
+    if (parseBareCommandArgs(ctx, args, usage))
+        return 0;
+    const registration = addCompanion(ctx.cwd, ctx.home);
+    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`);
+    return 0;
+}

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 { companionsPath, ITEM_NAMES, layoutOf, renderItemLocation, } from "../project-layout.js";
+import { registryPath, 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) {
@@ -67,11 +67,11 @@ function inspectConfig(ctx, resolved) {
     return lines;
 }
 function inspectCompanion(ctx) {
-    const path = companionsPath(ctx.home);
+    const path = registryPath(ctx.home);
     const layout = layoutOf(ctx);
     const file = {
         level: "ok",
-        text: `companions.json ${existsSync(path) ? "valid" : "absent"} (${path})`,
+        text: `registry ${existsSync(path) ? "valid" : "absent"} (${path})`,
     };
     if (layout.companion === null)
         return [file, { level: "ok", text: "none" }];

package/dist/project-layout.d.ts

@@ -23,8 +23,21 @@ export interface ItemLocation {
 }
 export declare function layoutOf(ctx: CommandContext): ProjectLayout;
 export declare function resolveProjectLayout(cwd: string, home: string): ProjectLayout;
-export declare function companionsPath(home: string): string;
+export declare function registryPath(home: string): string;
 /** One line: `<name>: <path> (<in>)`, with `, missing` when absent. */
 export declare function renderItemLocation(name: ItemName, location: ItemLocation): string;
 /** The `_aligndev` tree when it is not the resolved `.plans` and exists. */
 export declare function separateSessionTree(layout: ProjectLayout): string | undefined;
+export interface CompanionRegistration {
+    registry: string;
+    /** The key added, or the most specific key that already matched. */
+    key: string;
+    added: boolean;
+    /** Absolute. */
+    dir: string;
+}
+/**
+ * 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.
+ */
+export declare function addCompanion(cwd: string, home: string): CompanionRegistration;

package/dist/project-layout.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, 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";
@@ -12,8 +12,9 @@ export const ITEM_NAMES = [
     ".plans",
     "_aligndev",
 ];
-// The directory holding the companions. A symlink there moves them elsewhere.
+// 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",
@@ -24,7 +25,7 @@ const flagsSchema = type({
     ".plans?": FLAG,
     "_aligndev?": FLAG,
 });
-const companionsSchema = type({
+const registrySchema = type({
     "+": "reject",
     paths: type.Record("string", flagsSchema),
 });
@@ -37,23 +38,23 @@ export function resolveProjectLayout(cwd, home) {
     return { companion, locations: resolveLocations(cwd, companion) };
 }
 function resolveCompanion(cwd, home) {
-    const file = readCompanionsFile(home);
-    if (file === undefined)
+    const registry = readRegistry(home);
+    if (registry === undefined)
         return null;
     const mainWorktree = findMainWorktree(cwd);
     if (mainWorktree === undefined)
         return null;
     const realHome = realOrResolved(home);
-    const matches = matchingEntries(file, mainWorktree, realHome);
+    const matches = matchingEntries(registry, mainWorktree, realHome);
     if (matches.length === 0)
         return null;
     const flags = mergeFlags(matches);
-    assertValidFlags(file, flags, matches);
-    const dir = join(normalizePath(COMPANIONS_ROOT, realHome), companionName(mainWorktree, realHome));
+    assertValidFlags(registry, flags, matches);
+    const dir = companionDir(mainWorktree, realHome);
     return { dir, exists: pathExists(dir), entries: matches.map((match) => match.key), flags };
 }
-function readCompanionsFile(home) {
-    const path = companionsPath(home);
+function readRegistry(home) {
+    const path = registryPath(home);
     if (!pathExists(path))
         return;
     let value;
@@ -61,20 +62,20 @@ function readCompanionsFile(home) {
         value = JSON.parse(readFileSync(path, "utf-8"));
     }
     catch (error) {
-        throw invalidCompanions(path, errorMessage(error));
+        throw invalidRegistry(path, errorMessage(error));
     }
-    const file = companionsSchema(value);
+    const file = registrySchema(value);
     if (file instanceof type.errors)
-        throw invalidCompanions(path, file.summary.split("\n", 1)[0]);
+        throw invalidRegistry(path, file.summary.split("\n", 1)[0]);
     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}`);
+        throw invalidRegistry(path, `paths key must be an absolute path or start with ~/: ${badKey}`);
     return { path, paths: file.paths };
 }
-export function companionsPath(home) {
-    return join(home, ".alignfirst", "companions.json");
+export function registryPath(home) {
+    return join(home, ".alignfirst", "companions", REGISTRY_FILE);
 }
-function invalidCompanions(path, detail) {
+function invalidRegistry(path, detail) {
     return new CliError(`Invalid ${path}: ${detail}`);
 }
 function isUserPath(value) {
@@ -95,8 +96,8 @@ function normalizePath(value, realHome) {
 function realOrResolved(path) {
     return existsSync(path) ? realpathSync(path) : resolve(path);
 }
-function matchingEntries(file, mainWorktree, realHome) {
-    return Object.entries(file.paths)
+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);
@@ -115,11 +116,14 @@ function mergeFlags(matches) {
         _aligndev: flagOf("_aligndev"),
     };
 }
-function assertValidFlags(file, flags, matches) {
+function assertValidFlags(registry, 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})`);
+    throw invalidRegistry(registry.path, `"_aligndev": true requires ".plans" set to true or false (matching keys: ${keys})`);
+}
+function companionDir(mainWorktree, realHome) {
+    return join(normalizePath(COMPANIONS_ROOT, realHome), companionName(mainWorktree, realHome));
 }
 function companionName(mainWorktree, realHome) {
     const name = mainWorktree !== realHome && isSameOrInside(mainWorktree, realHome)
@@ -171,3 +175,33 @@ export function separateSessionTree(layout) {
         return;
     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.
+ */
+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.");
+    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 dir = companionDir(mainWorktree, realHome);
+    mkdirSync(dir, { recursive: true });
+    return { registry: registry.path, key, added: match === undefined, dir };
+}
+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`;
+    writeFileSync(tmpPath, `${JSON.stringify({ paths }, undefined, 2)}\n`);
+    renameSync(tmpPath, registry.path);
+}

package/package.json

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