alignfirst 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # 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 plans repository.
+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 work-files repository.
 
 ## Agent skills
 
@@ -45,7 +45,7 @@ These examples use the `/` form. Replace it with `$` in Codex.
 
 To implement a plan, start a fresh agent context and ask it to execute the plan file.
 
-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`.
+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
 
@@ -81,8 +81,8 @@ The guide installs the selected components and configures the repository. You ca
 
 - `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.
+- `sync` — Synchronize the work files with the work-files repository.
+- `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 documentation map when `docs/` exists, and the protocol aliases.

package/dist/cli.js

@@ -39,7 +39,8 @@ export async function main(options) {
             ctx.projectConfig = resolveProjectConfig(ctx.cwd);
             checkCliRange(ctx.projectConfig?.config, ctx.version, [command, ...args]);
         }
-        return dispatch(ctx, command, args);
+        const code = await dispatch(ctx, command, args);
+        return code;
     }
     catch (error) {
         if (!(error instanceof CliError))
@@ -55,7 +56,7 @@ function readPackageVersion() {
     return pkg.version;
 }
 function renderHelp(ctx) {
-    return `alignfirst — protocols, plans and docs in one command.
+    return `alignfirst — protocols, work files and docs in one command.
 
 Usage:
   ${ctx.form} guide [<protocol>]

package/dist/commands/doctor.js

@@ -22,7 +22,7 @@ export function runDoctor(ctx, args) {
         return inspectConfig(ctx, resolved);
     });
     writeSection(ctx, "Git", () => inspectGit(ctx, resolved));
-    writeSection(ctx, "Plans", () => inspectPlans(ctx));
+    writeSection(ctx, "Work files", () => inspectPlans(ctx));
     writeSection(ctx, "Docmap", () => inspectDocmap(ctx));
     writeSection(ctx, "Skills", () => inspectSkills(ctx));
     return 0;

package/dist/commands/plans.js

@@ -51,10 +51,10 @@ function runSetup(ctx, args) {
 }
 function createPlansDirectory(cloneDir, folder) {
     if (folder.length === 0 || folder === "." || folder === ".." || /[\\/]/u.test(folder)) {
-        throw new CliError(`Plans folder "${folder}" must be a single path segment.`);
+        throw new CliError(`Project folder "${folder}" must be a single path segment.`);
     }
     if (RESERVED_PLANS_FOLDERS.has(folder.toLowerCase())) {
-        throw new CliError(`Plans folder "${folder}" is reserved.`);
+        throw new CliError(`Project folder "${folder}" is reserved.`);
     }
     const cloneRoot = realpathSync(cloneDir);
     const projectDir = join(cloneRoot, folder);
@@ -64,7 +64,7 @@ function createPlansDirectory(cloneDir, folder) {
         relativeTarget === ".." ||
         relativeTarget.startsWith(`..${sep}`) ||
         isAbsolute(relativeTarget)) {
-        throw new CliError(`Plans folder "${folder}" must resolve inside ${cloneRoot}.`);
+        throw new CliError(`Project folder "${folder}" must resolve inside ${cloneRoot}.`);
     }
     return projectDir;
 }
@@ -94,11 +94,11 @@ function parseSetupArgs(ctx, args, usage) {
 }
 function checkClone(ctx, cloneDir) {
     if (!existsSync(cloneDir))
-        throw new CliError(`${cloneDir} does not exist. Clone the team plans repository there first (see the instruction file).`);
+        throw new CliError(`${cloneDir} does not exist. Clone the work-files repository there first (see the instruction file).`);
     if (!existsSync(join(cloneDir, ".git")))
-        throw new CliError(`${cloneDir} is not a git repository. Point ${ctx.form} plans setup at a clone of the team plans repository.`);
+        throw new CliError(`${cloneDir} is not a git repository. Point ${ctx.form} plans setup at a clone of the work-files repository.`);
     if (realpathSync(cloneDir) === realpathSync(ctx.cwd))
-        throw new CliError(`${cloneDir} is the product repository itself. Point ${ctx.form} plans setup at a clone of the team plans repository.`);
+        throw new CliError(`${cloneDir} is the product repository itself. Point ${ctx.form} plans setup at a clone of the work-files repository.`);
 }
 function runCheck(ctx, args) {
     const usage = `Usage: ${ctx.form} plans check\n`;
@@ -111,9 +111,9 @@ function runCheck(ctx, args) {
             throw new CliError(renderStoppedRebase(stopped, ctx.form));
     }
     if (mode.kind === "shared")
-        ctx.stdout.write(".plans is linked to the team plans repository.\n");
+        ctx.stdout.write(".plans is linked to the work-files repository.\n");
     else
-        ctx.stdout.write(".plans is a local directory (local plans mode): synchronization is disabled.\n");
+        ctx.stdout.write(".plans is a local directory (local mode): synchronization is disabled.\n");
     return 0;
 }
 function runAutoArchive(ctx, args) {

package/dist/commands/sync.d.ts

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

package/dist/commands/sync.js

@@ -6,7 +6,7 @@ import { parseCommandArgs } from "../parse-args.js";
 import { archiveThresholdDays, autoArchive } from "../plans/archive.js";
 import { resolvePlansMode } from "../plans/mode.js";
 import { findStoppedRebase, renderStoppedRebase, resolveStoppedRebase } from "../plans/rebase.js";
-export function runSync(ctx, args) {
+export async function runSync(ctx, args) {
     const usage = `Usage: ${ctx.form} sync [--auto-archive | --no-auto-archive]\n`;
     const options = parseSyncArgs(ctx, args, usage);
     if (options === undefined)
@@ -22,40 +22,40 @@ export function runSync(ctx, args) {
     if (mode.kind === "local") {
         if (thresholdDays !== undefined)
             autoArchive(plansDir, thresholdDays, ctx.stdout);
-        ctx.stdout.write("(local plans mode, nothing to sync)\n");
+        ctx.stdout.write("(local mode, nothing to sync)\n");
         return 0;
     }
     const repoDir = mode.repoToplevel;
     assertNoStoppedRebase(repoDir, ctx.form);
-    git(repoDir, "add", "-A");
+    await git(ctx, repoDir, "add", "-A");
     if (hasStagedChanges(repoDir))
-        git(repoDir, "commit", "--quiet", "-m", "sync");
+        await git(ctx, repoDir, "commit", "--quiet", "-m", "sync");
     if (hasUpstream(repoDir)) {
         try {
-            git(repoDir, "pull", "--rebase");
+            await git(ctx, repoDir, "pull", "--rebase");
         }
         catch {
             if (findStoppedRebase(repoDir) === undefined)
                 throw new CliError("git pull failed. See the git output above.");
-            resolveStoppedRebase(repoDir, ctx.stdout);
+            await resolveStoppedRebase(ctx, repoDir);
         }
     }
     if (thresholdDays !== undefined && autoArchive(plansDir, thresholdDays, ctx.stdout)) {
-        git(repoDir, "add", "-A");
+        await git(ctx, repoDir, "add", "-A");
         if (hasStagedChanges(repoDir))
-            git(repoDir, "commit", "--quiet", "-m", "sync");
+            await git(ctx, repoDir, "commit", "--quiet", "-m", "sync");
     }
     if (hasCommitsToSend(repoDir)) {
         try {
-            git(repoDir, "push", "--quiet", "-u", "origin", "HEAD");
+            await git(ctx, repoDir, "push", "--quiet", "-u", "origin", "HEAD");
         }
         catch {
             throw new CliError(`git push failed. See the git output above. Another synchronization may have landed first: run ${ctx.form} sync again.`);
         }
-        ctx.stdout.write("Plans synchronized: local changes sent.\n");
+        ctx.stdout.write("Work files synchronized: local changes sent.\n");
     }
     else {
-        ctx.stdout.write("Plans synchronized: nothing to send.\n");
+        ctx.stdout.write("Work files synchronized: nothing to send.\n");
     }
     return 0;
 }

package/dist/context.d.ts

@@ -2,12 +2,14 @@ import type { ResolvedProjectConfig } from "./project-config.js";
 export interface Output {
     write(text: string): void;
 }
-export interface CommandContext {
+export interface Streams {
+    stdout: Output;
+    stderr: Output;
+}
+export interface CommandContext extends Streams {
     cwd: string;
     env: NodeJS.ProcessEnv;
     home: string;
-    stdout: Output;
-    stderr: Output;
     form: string;
     version: string;
     projectConfig?: ResolvedProjectConfig;

package/dist/conventions.js

@@ -49,17 +49,17 @@ function renderPlans(ctx) {
     try {
         const mode = resolvePlansMode(ctx.cwd, ctx.form);
         const folder = ctx.projectConfig?.config.plans?.folder;
-        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`, a separate git repository)`;
+        const sharedFolder = folder === undefined ? "" : ` (folder \`${folder}\` in the work-files repository)`;
         const base = mode.kind === "shared"
-            ? `Plans: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
-            : "Plans: use `.plans`.";
+            ? `Work files: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
+            : "Work files: use `.plans`.";
         const archival = ctx.projectConfig?.config.plans?.autoArchive === true
             ? " Automatic archival is enabled."
             : "";
         return `${base}${archival}`;
     }
     catch (error) {
-        return `Plans: ${errorMessage(error).split("\n", 1)[0]}`;
+        return `Work files: ${errorMessage(error).split("\n", 1)[0]}`;
     }
 }
 function plansEntryExists(cwd) {

package/dist/git.d.ts

@@ -1,6 +1,8 @@
-export declare function git(dir: string, ...args: string[]): void;
+import type { Streams } from "./context.js";
+export declare function git(streams: Streams, dir: string, ...args: string[]): Promise<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 gitBuffer(dir: string, ...args: string[]): Buffer;
 export declare function gitOutputOrUndefined(dir: string, ...args: string[]): string | undefined;
 export declare function gitSucceeds(dir: string, ...args: string[]): boolean;

package/dist/git.js

@@ -1,17 +1,33 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { CliError } from "./cli-error.js";
-export function git(dir, ...args) {
-    try {
-        execFileSync("git", ["-C", dir, ...args], { stdio: "inherit" });
-    }
-    catch {
-        throw gitFailure(args);
-    }
+export function git(streams, dir, ...args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["-C", dir, ...args], {
+            stdio: ["inherit", "pipe", "pipe"],
+        });
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (text) => streams.stdout.write(text));
+        child.stderr.on("data", (text) => streams.stderr.write(text));
+        child.once("error", (error) => reject(gitFailure(args, error.message)));
+        child.once("close", (code) => (code === 0 ? resolve() : reject(gitFailure(args))));
+    });
+}
+function gitFailure(args, detail) {
+    const output = detail?.trim();
+    const subcommand = gitSubcommand(args);
+    const label = subcommand === undefined ? "git command" : `git ${subcommand}`;
+    if (output === undefined || output === "")
+        return new CliError(`${label} failed. See the git output above.`);
+    return new CliError(`${label} failed:\n${output}`);
 }
-function gitFailure(args) {
-    return new CliError(`git ${args[0]} failed. See the git output above.`);
+function gitSubcommand(args) {
+    let index = 0;
+    while (args[index] === "-c")
+        index += 2;
+    return args[index];
 }
 export function assertMainWorktreeRoot(cwd) {
     const toplevel = gitOutput(cwd, "rev-parse", "--show-toplevel");
@@ -26,18 +42,20 @@ export function gitOutput(dir, ...args) {
     return gitOutputRaw(dir, ...args).trim();
 }
 export function gitOutputRaw(dir, ...args) {
-    let output;
-    try {
-        output = execFileSync("git", ["-C", dir, ...args]);
-    }
-    catch {
-        throw gitFailure(args);
-    }
+    const output = gitBuffer(dir, ...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 gitBuffer(dir, ...args) {
+    const result = spawnSync("git", ["-C", dir, ...args]);
+    if (result.error !== undefined)
+        throw gitFailure(args, result.error.message);
+    if (result.status !== 0)
+        throw gitFailure(args, result.stderr.toString("utf8"));
+    return result.stdout;
+}
 export function gitOutputOrUndefined(dir, ...args) {
     try {
         return execFileSync("git", ["-C", dir, ...args], {

package/dist/plans/conflicts.d.ts

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

package/dist/plans/conflicts.js

@@ -1,10 +1,9 @@
-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 { gitBuffer, gitOutput, gitOutputRaw } from "../git.js";
 import { nextFilePosition } from "./ticket.js";
-export function resolveConflictedPaths(repoDir, stdout) {
+export function resolveConflictedPaths(streams, repoDir) {
     const conflicts = readConflicts(repoDir);
     const remote = readTree(repoDir, "HEAD");
     const local = readTree(repoDir, "REBASE_HEAD");
@@ -35,7 +34,7 @@ export function resolveConflictedPaths(repoDir, stdout) {
     applyResolution(repoDir, conflicts, resolution);
     for (const path of conflicts.keys()) {
         const renamed = resolution.renames.get(path);
-        stdout.write(renamed === undefined
+        streams.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`);
     }
@@ -49,7 +48,7 @@ function readConflicts(repoDir) {
         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.");
+            throw new CliError("Could not read the git index of the work-files repository.");
         const path = entry.slice(tab + 1);
         const stages = result.get(path) ?? new Set();
         stages.add(stage);
@@ -177,7 +176,7 @@ function assertNoLaterEdits(repoDir, renames) {
     }
 }
 function readBlob(repoDir, blob) {
-    return execFileSync("git", ["-C", repoDir, "cat-file", "blob", blob.id]);
+    return gitBuffer(repoDir, "cat-file", "blob", blob.id);
 }
 function updateReferences(original, source, renames) {
     const replacements = new Map();
@@ -187,7 +186,7 @@ function updateReferences(original, source, renames) {
         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.
+        // A work-files repository clone stores the project's .plans directory under its configured folder.
         replacements.set(before.replace(/^[^/]+\//, ".plans/"), after.replace(/^[^/]+\//, ".plans/"));
     }
     if (replacements.size === 0)

package/dist/plans/layout.js

@@ -25,7 +25,7 @@ export function assertPlansGate(cwd, form) {
     return stats;
 }
 export function missingPlansMessage(form) {
-    return `No .plans/ directory in the current directory.\nLocal plans:  mkdir .plans && echo .plans >> .gitignore\nTeam plans:   ${form} plans setup <clone-dir>`;
+    return `No .plans/ directory in the current directory.\nLocal work files:  mkdir .plans && echo .plans >> .gitignore\nTeam work files:   ${form} plans setup <clone-dir>`;
 }
 export function missingPlansError(form) {
     return new CliError(missingPlansMessage(form));

package/dist/plans/link.js

@@ -6,7 +6,7 @@ export function linkPlans(ctx, targetDir) {
     const stats = lstatSync(plansPath, { throwIfNoEntry: false });
     if (stats?.isSymbolicLink()) {
         if (existsSync(plansPath) && realpathSync(plansPath) === realpathSync(targetDir)) {
-            ctx.stdout.write(".plans already links to the plans repository.\n");
+            ctx.stdout.write(".plans already links to the work-files repository.\n");
             return;
         }
         rmSync(plansPath);

package/dist/plans/rebase.d.ts

@@ -1,8 +1,8 @@
-import type { Output } from "../context.js";
+import type { Streams } 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 resolveStoppedRebase(streams: Streams, repoDir: string): Promise<void>;
 export declare function renderStoppedRebase(stopped: StoppedRebase, form: string): string;

package/dist/plans/rebase.js

@@ -17,26 +17,26 @@ export function findStoppedRebase(repoDir) {
         conflictedFiles: conflicts.split("\0").filter((path) => path !== ""),
     };
 }
-export function resolveStoppedRebase(repoDir, stdout) {
+export async function resolveStoppedRebase(streams, repoDir) {
     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);
+        resolveConflictedPaths(streams, repoDir);
+        await git(streams, repoDir, "add", "-A");
+        await continueRebase(streams, repoDir);
     }
 }
-function continueRebase(repoDir) {
+async function continueRebase(streams, repoDir) {
     const args = ["-c", "core.editor=true", "rebase", "--continue"];
     try {
-        git(repoDir, ...args);
+        await git(streams, repoDir, ...args);
     }
     catch (error) {
         const stopped = findStoppedRebase(repoDir);
         if (stopped?.conflictedFiles.length)
             return;
         if (stopped && gitSucceeds(repoDir, "diff", "--cached", "--quiet")) {
-            git(repoDir, "rebase", "--skip");
+            await git(streams, repoDir, "rebase", "--skip");
             return;
         }
         throw error;
@@ -45,7 +45,7 @@ function continueRebase(repoDir) {
 export function renderStoppedRebase(stopped, form) {
     const files = stopped.conflictedFiles.map((path) => `  ${path}`);
     return [
-        `Plans synchronization stopped on a conflict in ${stopped.repoDir}:`,
+        `Work-files synchronization stopped on a conflict in ${stopped.repoDir}:`,
         ...files,
         "Resolve the markers in these files, then run:",
         `  git -C ${stopped.repoDir} add -A && git -C ${stopped.repoDir} rebase --continue`,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "alignfirst",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
-  "description": "The AlignFirst CLI: protocols, plans and docs in one command.",
+  "description": "The AlignFirst CLI: protocols, work files and docs in one command.",
   "keywords": [
     "alignfirst",
     "cli",

package/templates/guide/code-review/reviewer-common.md

@@ -5,7 +5,7 @@ You are one of several reviewers examining the same branch, each from a differen
 ## Scope
 
 - Review the changes between the merge-base and HEAD (the orchestrator gives you both): `git diff <merge_base> HEAD`. The review target is the branch as committed.
-- Fresh eyes: derive everything from the code and the diff. Do not read specs, plans, summaries, or any file in the task directory (e.g., under `.plans/`).
+- Fresh eyes: derive everything from the code and the diff. Do not read specs, plans, summaries, or any file in the ticket directory (under `.plans/`).
 - Read-only: never modify the working tree, the index, or HEAD.
 
 ## Method