alignfirst 0.2.0 → 0.3.0

package/README.md

@@ -1,56 +1,10 @@
 # alignfirst
 
-The AlignFirst CLI provides collaborative software-development workflows, work files, and documentation discovery. Work files are organized by ticket and kept either git-ignored in the project or synchronized through a team repository.
-
-## Installation
-
-Install it globally:
-
-```sh
-npm install -g alignfirst
-```
-
-Or run the current version without installing it:
-
-```sh
-npx alignfirst
-```
-
-## Setup with your agent
-
-Temporarily install the setup-guide skill:
-
-```sh
-npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guide
-```
-
-Then ask your agent:
-
-```text
-Use your alignfirst-setup-guide skill. Set up AlignFirst in this project. Ask before installing anything globally.
-```
-
-The guide installs the selected components and configures the repository. Remove the setup-guide skill when setup is complete.
-
-## Commands
-
-- `guide` — Print an AlignFirst protocol.
-- `ticket` — Resolve a ticket directory, load its history, or get its next file.
-- `sync` — Synchronize shared plans.
-- `plans` — Set up, check and archive plans.
-- `docmap` — Browse project documentation.
-- `conventions` — Print the effective project conventions.
-- `context` — Print the conventions, the documentation map when `docs/` exists, and the protocol aliases.
-- `config` — Report the effective project configuration.
-- `doctor` — Diagnose an AlignFirst setup.
-
-Run `alignfirst --help` for command usage or `alignfirst guide` to choose a protocol. `alignfirst guide <protocol>` prints the selected protocol followed by the ticket directory and work file rules. Add `--protocol-only` when those rules are already in context.
+The AlignFirst CLI provides collaborative software-development workflows, work files, and documentation discovery. Work files are organized by ticket and kept either git-ignored in the project or synchronized through a team plans repository.
 
 ## Agent skills
 
-Nine optional Agent Skill stubs expose the CLI as commands in Claude Code, Codex, GitHub Copilot, and Cursor. Protocol skills reuse guides already in context and load missing guides through `npx -y alignfirst guide`. Catchup skills load ticket history through `npx -y alignfirst ticket --catchup`.
-
-Install them globally:
+Nine Agent Skill stubs expose the CLI as commands in Claude Code, Codex, GitHub Copilot, and Cursor. Install them globally:
 
 ```sh
 npx skills add https://github.com/paleo/alignfirst --global \
@@ -65,7 +19,13 @@ Install the `alignfirst` skill when a project's `AGENTS.md` does not run `npx al
 npx skills add https://github.com/paleo/alignfirst --global --skill alignfirst
 ```
 
-Start a new agent session to load the skills.
+The skills run the CLI through `npx`, so installing it is optional.
+
+### Update the agent skills
+
+```sh
+npx skills update --global
+```
 
 ## Workflows
 
@@ -87,17 +47,54 @@ To implement a plan, start a fresh agent context and ask it to execute the plan
 
 AlignFirst stores 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`.
 
-## Catchup output
+## Global CLI
+
+To type `alignfirst` instead of `npx alignfirst`, install the CLI globally:
+
+```sh
+npm install -g alignfirst
+```
+
+### Update the global CLI
 
-`alignfirst ticket [<id>] --catchup` prints the ticket's Markdown files, plans excluded, each in a `<file>` block carrying its path and modification time. When the history exceeds the output budget, only the entry list is printed, with a notice telling the agent to read the relevant files and skip the plans.
+```sh
+npm update -g alignfirst
+```
 
-## Updates
+## Set up a project (with your agent)
+
+Temporarily install the setup-guide skill:
 
 ```sh
-npm install -g alignfirst@latest
-npx skills update --global --yes
+npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guide
+```
+
+Then ask your agent:
+
+```text
+Use your alignfirst-setup-guide skill. What AlignFirst tooling could we add in this project?
 ```
 
+The guide installs the selected components and configures the repository. You can remove the setup-guide skill once setup is complete.
+
+## CLI commands
+
+- `guide` — Print an AlignFirst protocol.
+- `ticket` — Resolve a ticket directory, load its history, or get its next file.
+- `sync` — Synchronize shared plans.
+- `plans` — Set up, check and archive plans.
+- `docmap` — Browse project documentation.
+- `conventions` — Print the effective project conventions.
+- `context` — Print the conventions, the documentation map when `docs/` exists, and the protocol aliases.
+- `config` — Report the effective project configuration.
+- `doctor` — Diagnose an AlignFirst setup.
+
+Run `alignfirst --help` for command usage or `alignfirst guide` to choose a protocol. `alignfirst guide <protocol>` prints the selected protocol followed by the ticket directory and work file rules. Add `--protocol-only` when those rules are already in context.
+
+### Catchup output
+
+`alignfirst ticket [<id>] --catchup` prints the ticket's Markdown files, plans excluded.
+
 ## Upgrade from v1, v2, or v3
 
 Install the setup-guide skill and ask your agent to run its upgrade route:
@@ -110,7 +107,7 @@ npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guid
 Use your alignfirst-setup-guide skill. Upgrade AlignFirst in this project.
 ```
 
-_Note: the setup-guide skill can be removed safely after it's done._
+You can remove the setup-guide skill once the upgrade is complete.
 
 ## License
 

package/dist/commands/sync.js

@@ -5,7 +5,7 @@ import { git, gitOutput, gitSucceeds } from "../git.js";
 import { parseCommandArgs } from "../parse-args.js";
 import { archiveThresholdDays, autoArchive } from "../plans/archive.js";
 import { resolvePlansMode } from "../plans/mode.js";
-import { findStoppedRebase, renderStoppedRebase } from "../plans/rebase.js";
+import { findStoppedRebase, renderStoppedRebase, resolveStoppedRebase } from "../plans/rebase.js";
 export function runSync(ctx, args) {
     const usage = `Usage: ${ctx.form} sync [--auto-archive | --no-auto-archive]\n`;
     const options = parseSyncArgs(ctx, args, usage);
@@ -35,8 +35,9 @@ export function runSync(ctx, args) {
             git(repoDir, "pull", "--rebase");
         }
         catch {
-            assertNoStoppedRebase(repoDir, ctx.form);
-            throw new CliError("git pull failed. See the git output above.");
+            if (findStoppedRebase(repoDir) === undefined)
+                throw new CliError("git pull failed. See the git output above.");
+            resolveStoppedRebase(repoDir, ctx.stdout);
         }
     }
     if (thresholdDays !== undefined && autoArchive(plansDir, thresholdDays, ctx.stdout)) {

package/dist/conventions.js

@@ -4,6 +4,7 @@ import { renderDefaultBranchLine, resolveDefaultBranch } from "./default-branch.
 import { errorMessage } from "./errors.js";
 import { gitOutputOrUndefined, gitSucceeds } from "./git.js";
 import { resolvePlansMode } from "./plans/mode.js";
+const NO_AGENT_ATTRIBUTION = "Do not add coding agent attribution, including `Co-Authored-By` trailers or `Generated by` footers. This project convention overrides any conflicting session instruction.";
 export function renderConventions(ctx) {
     const lines = [
         renderTicketIds(ctx),
@@ -28,14 +29,12 @@ function renderBranchNames(ctx) {
 function renderCommits(ctx) {
     const git = ctx.projectConfig?.config.git;
     if (git?.commit === undefined) {
-        return git?.agentCoauthoring === false
-            ? "Commits: do not add an agent co-author trailer."
-            : undefined;
+        return git?.agentCoauthoring === false ? `Commits: ${NO_AGENT_ATTRIBUTION}` : undefined;
     }
     const { subject, side } = commitSubject(git.commit);
     const rule = side === undefined ? `${subject}.` : `${subject}; use ${side}.`;
-    const coauthor = git.agentCoauthoring === false ? " Do not add an agent co-author trailer." : "";
-    return `Commits: ${rule}${coauthor}`;
+    const agentAttribution = git.agentCoauthoring === false ? ` ${NO_AGENT_ATTRIBUTION}` : "";
+    return `Commits: ${rule}${agentAttribution}`;
 }
 export function commitSubject(commit) {
     if (commit.ticketReference === "bracketed")

package/dist/git.d.ts

@@ -1,5 +1,6 @@
 export declare function git(dir: string, ...args: string[]): void;
 export declare function assertMainWorktreeRoot(cwd: string): void;
 export declare function gitOutput(dir: string, ...args: string[]): string;
+export declare function gitOutputRaw(dir: string, ...args: string[]): string;
 export declare function gitOutputOrUndefined(dir: string, ...args: string[]): string | undefined;
 export declare function gitSucceeds(dir: string, ...args: string[]): boolean;

package/dist/git.js

@@ -23,12 +23,20 @@ export function assertMainWorktreeRoot(cwd) {
         throw new CliError("Run this command from the main worktree. Linked worktrees reach .plans through it.");
 }
 export function gitOutput(dir, ...args) {
+    return gitOutputRaw(dir, ...args).trim();
+}
+export function gitOutputRaw(dir, ...args) {
+    let output;
     try {
-        return execFileSync("git", ["-C", dir, ...args], { encoding: "utf-8" }).trim();
+        output = execFileSync("git", ["-C", dir, ...args]);
     }
     catch {
         throw gitFailure(args);
     }
+    const text = output.toString("utf8");
+    if (!Buffer.from(text).equals(output))
+        throw new CliError("Cannot read non-UTF-8 Git output safely. Resolve the rebase manually.");
+    return text;
 }
 export function gitOutputOrUndefined(dir, ...args) {
     try {

package/dist/plans/conflicts.d.ts

@@ -0,0 +1,2 @@
+import type { Output } from "../context.js";
+export declare function resolveConflictedPaths(repoDir: string, stdout: Output): void;

package/dist/plans/conflicts.js

@@ -0,0 +1,234 @@
+import { execFileSync } from "node:child_process";
+import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { CliError } from "../cli-error.js";
+import { gitOutput, gitOutputRaw } from "../git.js";
+import { nextFilePosition } from "./ticket.js";
+export function resolveConflictedPaths(repoDir, stdout) {
+    const conflicts = readConflicts(repoDir);
+    const remote = readTree(repoDir, "HEAD");
+    const local = readTree(repoDir, "REBASE_HEAD");
+    const resolution = {
+        files: new Map(),
+        renames: new Map(),
+        reserved: new Set([...remote.keys(), ...local.keys()]),
+    };
+    for (const [path, stages] of conflicts) {
+        const ours = conflictBlob(path, stages.has(2), remote);
+        const theirs = conflictBlob(path, stages.has(3), local);
+        if (!ours && !theirs && (remote.has(path) || local.has(path)))
+            throw new CliError(`Cannot recover both versions of ${path}. Resolve the rebase manually.`);
+        if (ours)
+            resolution.files.set(path, { blob: ours });
+        if (!theirs)
+            continue;
+        if (ours && (ours.id !== theirs.id || ours.mode !== theirs.mode)) {
+            preserveLocalCopy(repoDir, path, theirs, resolution);
+        }
+        else {
+            resolution.files.set(path, { blob: theirs, localPath: path });
+        }
+    }
+    preserveCompanionSummaries(repoDir, remote, local, resolution);
+    preserveLocalReferences(repoDir, remote, local, resolution);
+    assertNoLaterEdits(repoDir, resolution.renames);
+    applyResolution(repoDir, conflicts, resolution);
+    for (const path of conflicts.keys()) {
+        const renamed = resolution.renames.get(path);
+        stdout.write(renamed === undefined
+            ? `Resolved ${path}: preserved committed contents at the surviving paths.\n`
+            : `Resolved ${path}: kept the published version; saved the local version as ${renamed}.\n`);
+    }
+}
+function readConflicts(repoDir) {
+    const result = new Map();
+    for (const entry of gitOutputRaw(repoDir, "ls-files", "-u", "-z").split("\0")) {
+        if (entry === "")
+            continue;
+        const tab = entry.indexOf("\t");
+        const header = entry.slice(0, tab).split(" ");
+        const stage = Number(header[2]);
+        if (tab === -1 || ![1, 2, 3].includes(stage))
+            throw new CliError("Could not read the conflicted plans index.");
+        const path = entry.slice(tab + 1);
+        const stages = result.get(path) ?? new Set();
+        stages.add(stage);
+        result.set(path, stages);
+    }
+    return result;
+}
+function readTree(repoDir, commit) {
+    const result = new Map();
+    for (const entry of gitOutputRaw(repoDir, "ls-tree", "-r", "-z", commit).split("\0")) {
+        if (entry === "")
+            continue;
+        const tab = entry.indexOf("\t");
+        const [mode, , id] = entry.slice(0, tab).split(" ");
+        result.set(entry.slice(tab + 1), { id, mode });
+    }
+    return result;
+}
+function conflictBlob(path, present, tree) {
+    if (!present)
+        return;
+    const blob = tree.get(path);
+    if (!blob || !["100644", "100755"].includes(blob.mode))
+        throw new CliError(`Cannot automatically preserve conflict at ${path}. Resolve the rebase manually.`);
+    return blob;
+}
+function preserveLocalCopy(repoDir, path, blob, resolution) {
+    const target = freeLocalPath(repoDir, path, resolution.reserved);
+    resolution.renames.set(path, target);
+    resolution.reserved.add(target);
+    resolution.files.set(target, { blob, localPath: path });
+}
+function freeLocalPath(repoDir, path, reserved) {
+    const dir = dirname(path);
+    const names = [
+        ...readdirSync(join(repoDir, dir)),
+        ...[...reserved].filter((entry) => dirname(entry) === dir).map((entry) => basename(entry)),
+    ];
+    const name = basename(path);
+    const numbered = /^[A-Z]\d+-(.+)$/s.exec(name);
+    const { cycleLetter, fileNumber } = nextFilePosition(names, false);
+    const extension = name.endsWith(".summary.md") ? ".summary.md" : extname(name);
+    const stem = name.slice(0, name.length - extension.length);
+    for (let offset = 0;; ++offset) {
+        const candidate = join(dir, numbered
+            ? `${cycleLetter}${fileNumber + offset}-${numbered[1]}`
+            : `${stem}-local-${offset + 2}${extension}`);
+        if (reserved.has(candidate) || lstatSync(join(repoDir, candidate), { throwIfNoEntry: false }))
+            continue;
+        const companion = `${candidate.slice(0, -3)}.summary.md`;
+        if (name.endsWith(".md") &&
+            reserved.has(`${path.slice(0, -3)}.summary.md`) &&
+            (reserved.has(companion) || lstatSync(join(repoDir, companion), { throwIfNoEntry: false })))
+            continue;
+        return candidate;
+    }
+}
+function preserveCompanionSummaries(repoDir, remote, local, resolution) {
+    for (const [source, target] of resolution.renames) {
+        if (!source.endsWith(".md"))
+            continue;
+        const companion = `${source.slice(0, -3)}.summary.md`;
+        const blob = local.get(companion);
+        if (!blob)
+            continue;
+        const companionTarget = `${target.slice(0, -3)}.summary.md`;
+        if (resolution.reserved.has(companionTarget) ||
+            lstatSync(join(repoDir, companionTarget), { throwIfNoEntry: false }))
+            throw new CliError(`Cannot preserve related summary ${companion}: ${companionTarget} exists.`);
+        conflictBlob(companion, true, local);
+        const previousTarget = resolution.renames.get(companion);
+        if (previousTarget !== undefined)
+            resolution.files.delete(previousTarget);
+        resolution.renames.set(companion, companionTarget);
+        resolution.reserved.add(companionTarget);
+        resolution.files.set(companionTarget, { blob, localPath: companion });
+        const published = conflictBlob(companion, remote.has(companion), remote);
+        if (published)
+            resolution.files.set(companion, { blob: published });
+        else
+            resolution.files.delete(companion);
+    }
+}
+function preserveLocalReferences(repoDir, remote, local, resolution) {
+    if (resolution.renames.size === 0)
+        return;
+    const published = readTree(repoDir, rebaseCommit(repoDir, "onto"));
+    const added = new Set(gitOutputRaw(repoDir, "diff", "--cached", "--name-only", "--diff-filter=A", "-z")
+        .split("\0")
+        .filter((path) => path !== ""));
+    for (const [path, blob] of local) {
+        if (!path.endsWith(".md") ||
+            (!added.has(path) && (!remote.has(path) || published.has(path))) ||
+            resolution.renames.has(path))
+            continue;
+        if (blob.mode === "100644" || blob.mode === "100755")
+            resolution.files.set(path, { blob, localPath: path });
+    }
+}
+function rebaseCommit(repoDir, name) {
+    const state = gitOutput(repoDir, "rev-parse", "--git-path", `rebase-merge/${name}`);
+    const path = resolve(repoDir, state);
+    if (!lstatSync(path, { throwIfNoEntry: false }))
+        throw new CliError("Cannot read the original rebase commits. Resolve the rebase manually.");
+    return readFileSync(path, "utf8").trim();
+}
+function assertNoLaterEdits(repoDir, renames) {
+    if (renames.size === 0)
+        return;
+    const originalHead = rebaseCommit(repoDir, "orig-head");
+    const commits = gitOutput(repoDir, "rev-list", `REBASE_HEAD..${originalHead}`);
+    for (const commit of commits.split("\n").filter((value) => value !== "")) {
+        const tree = readTree(repoDir, commit);
+        const paths = gitOutputRaw(repoDir, "diff-tree", "--no-commit-id", "--name-only", "-r", "-z", commit);
+        for (const path of paths.split("\0")) {
+            if (renames.has(path))
+                throw new CliError(`Cannot automatically rename ${path}: a later local commit edits it. Resolve the rebase manually.`);
+            const blob = tree.get(path);
+            if (!path.endsWith(".md") || !blob || !["100644", "100755"].includes(blob.mode))
+                continue;
+            const content = readBlob(repoDir, blob);
+            if (!updateReferences(content, path, renames).equals(content))
+                throw new CliError(`A later local commit references a renamed document in ${path}. Resolve the rebase manually.`);
+        }
+    }
+}
+function readBlob(repoDir, blob) {
+    return execFileSync("git", ["-C", repoDir, "cat-file", "blob", blob.id]);
+}
+function updateReferences(original, source, renames) {
+    const replacements = new Map();
+    for (const [before, after] of renames) {
+        replacements.set(before, after);
+        const from = relative(dirname(source), before);
+        const to = relative(dirname(source), after);
+        replacements.set(from, to);
+        replacements.set(`./${from}`, `./${to}`);
+        // A shared plans clone stores the project's .plans directory under its configured folder.
+        replacements.set(before.replace(/^[^/]+\//, ".plans/"), after.replace(/^[^/]+\//, ".plans/"));
+    }
+    if (replacements.size === 0)
+        return original;
+    const pattern = [...replacements.keys()]
+        .sort((left, right) => right.length - left.length)
+        .map((path) => path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("|");
+    const text = original.toString("utf8");
+    if (!Buffer.from(text).equals(original))
+        return original;
+    const updated = text.replace(new RegExp(`(?<![\\w./-])(?:${pattern})(?=$|[\\s\x60'"<>()[\\]#:])`, "g"), (match) => replacements.get(match) ?? match);
+    return Buffer.from(updated);
+}
+function applyResolution(repoDir, conflicts, resolution) {
+    const removed = [...new Set([...conflicts.keys(), ...resolution.renames.keys()])].filter((path) => !resolution.files.has(path));
+    for (const path of [...removed, ...resolution.files.keys()])
+        assertRegularPath(repoDir, path);
+    const writes = [...resolution.files].map(([path, file]) => {
+        const original = readBlob(repoDir, file.blob);
+        const content = file.localPath !== undefined && path.endsWith(".md")
+            ? updateReferences(original, file.localPath, resolution.renames)
+            : original;
+        return { path, content, mode: file.blob.mode === "100755" ? 0o755 : 0o644 };
+    });
+    for (const path of removed)
+        rmSync(join(repoDir, path), { force: true });
+    for (const { path, content, mode } of writes) {
+        const target = join(repoDir, path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+        chmodSync(target, mode);
+    }
+}
+function assertRegularPath(repoDir, path) {
+    const stat = lstatSync(join(repoDir, path), { throwIfNoEntry: false });
+    if (stat && !stat.isFile())
+        throw new CliError(`Cannot automatically replace ${path}. Resolve the rebase manually.`);
+    for (let dir = dirname(path); dir !== "."; dir = dirname(dir)) {
+        const parent = lstatSync(join(repoDir, dir), { throwIfNoEntry: false });
+        if (parent && !parent.isDirectory())
+            throw new CliError(`Cannot automatically write through ${dir}. Resolve the rebase manually.`);
+    }
+}

package/dist/plans/rebase.d.ts

@@ -1,6 +1,8 @@
+import type { Output } from "../context.js";
 export interface StoppedRebase {
     repoDir: string;
     conflictedFiles: string[];
 }
 export declare function findStoppedRebase(repoDir: string): StoppedRebase | undefined;
+export declare function resolveStoppedRebase(repoDir: string, stdout: Output): void;
 export declare function renderStoppedRebase(stopped: StoppedRebase, form: string): string;

package/dist/plans/rebase.js

@@ -1,6 +1,9 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { gitOutputOrUndefined } from "../git.js";
+import { CliError } from "../cli-error.js";
+import { git, gitOutputRaw, gitOutputOrUndefined, gitSucceeds } from "../git.js";
+import { resolveConflictedPaths } from "./conflicts.js";
+const MAX_REBASE_STEPS = 100;
 export function findStoppedRebase(repoDir) {
     const inProgress = ["rebase-merge", "rebase-apply"].some((name) => {
         const path = gitOutputOrUndefined(repoDir, "rev-parse", "--git-path", name);
@@ -8,12 +11,37 @@ export function findStoppedRebase(repoDir) {
     });
     if (!inProgress)
         return;
-    const conflicts = gitOutputOrUndefined(repoDir, "diff", "--name-only", "--diff-filter=U");
+    const conflicts = gitOutputRaw(repoDir, "diff", "-z", "--name-only", "--diff-filter=U");
     return {
         repoDir,
-        conflictedFiles: conflicts?.split("\n").filter((path) => path !== "") ?? [],
+        conflictedFiles: conflicts.split("\0").filter((path) => path !== ""),
     };
 }
+export function resolveStoppedRebase(repoDir, stdout) {
+    for (let step = 0; findStoppedRebase(repoDir) !== undefined; ++step) {
+        if (step >= MAX_REBASE_STEPS)
+            throw new CliError(`Could not finish the stopped rebase in ${repoDir}.`);
+        resolveConflictedPaths(repoDir, stdout);
+        git(repoDir, "add", "-A");
+        continueRebase(repoDir);
+    }
+}
+function continueRebase(repoDir) {
+    const args = ["-c", "core.editor=true", "rebase", "--continue"];
+    try {
+        git(repoDir, ...args);
+    }
+    catch (error) {
+        const stopped = findStoppedRebase(repoDir);
+        if (stopped?.conflictedFiles.length)
+            return;
+        if (stopped && gitSucceeds(repoDir, "diff", "--cached", "--quiet")) {
+            git(repoDir, "rebase", "--skip");
+            return;
+        }
+        throw error;
+    }
+}
 export function renderStoppedRebase(stopped, form) {
     const files = stopped.conflictedFiles.map((path) => `  ${path}`);
     return [

package/package.json

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