alignfirst 0.1.0 → 0.2.0

package/dist/commands/guide.js

@@ -128,9 +128,10 @@ function renderCoreGuide(ctx, placeholders) {
 }
 function buildGuidePlaceholders(ctx, protocol) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
-    const detection = pattern === undefined ? undefined : detectTicketFromBranch(ctx.cwd, pattern);
+    const template = ctx.projectConfig?.config.git?.branchNameTemplate;
+    const detection = detectTicketFromBranch(ctx.cwd, pattern, template);
     return {
-        ticketCommand: detection?.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
+        ticketCommand: detection.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
         ticketDetection: renderTicketDetection(pattern, detection),
         plansState: renderPlansState(ctx),
         commitRule: renderCommitRule(ctx),
@@ -138,11 +139,11 @@ function buildGuidePlaceholders(ctx, protocol) {
     };
 }
 function renderTicketDetection(pattern, detection) {
+    if (detection.kind === "detected")
+        return `Current ticket: \`${detection.id}\` (from branch \`${detection.branch}\`). The id argument of \`{{CMD}} ticket\` is optional and defaults to it; pass an id only when the user names another ticket.`;
     if (pattern === undefined)
         return "Ask the user for the ticket ID when it is not given.";
-    if (detection?.kind === "detected")
-        return `Current ticket: \`${detection.id}\` (from branch \`${detection.branch}\`). The id argument of \`{{CMD}} ticket\` is optional and defaults to it; pass an id only when the user names another ticket.`;
-    if (detection?.kind === "noMatch")
+    if (detection.kind === "noMatch")
         return `No ticket id on branch \`${detection.branch}\`. Ask the user for the id.`;
     return "No ticket id: detached HEAD. Ask the user for the id.";
 }

package/dist/commands/ticket.js

@@ -5,7 +5,7 @@ import { formatLocalTimestamp, formatSize } from "../format.js";
 import { parseCommandArgs } from "../parse-args.js";
 import { renderCatchup } from "../plans/catchup.js";
 import { assertPlansGate } from "../plans/layout.js";
-import { deduceTicketFromBranch, deduceTicketFromExisting, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
+import { detectTicketFromBranch, deduceTicketFromExisting, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
 const USAGE = `Usage:
   {{FORM}} ticket [<id>] [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
   {{FORM}} ticket --side [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
@@ -70,10 +70,11 @@ function parseTicketArgs(ctx, args, usage) {
     if (values.catchup &&
         (values.side || values.next !== undefined || values.json || values["dry-run"]))
         throw new CliError(`--catchup cannot be combined with --side, --next, --json, or --dry-run.\n\n${usage}`);
+    const next = values.next === undefined ? undefined : resolveNextRequest(normalized.requests, usage);
     const resolution = resolveTicketId(ctx, positionals[0], values);
     return {
         ...resolution,
-        next: values.next === undefined ? undefined : resolveNextRequest(normalized.requests, usage),
+        next,
         newCycle: values["new-cycle"],
         json: values.json,
         dryRun: values["dry-run"],
@@ -125,16 +126,23 @@ function validateNextFilename(filename) {
 function resolveTicketId(ctx, positional, flags) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
     if (positional !== undefined) {
-        validateTicketId(positional, pattern);
+        validateTicketId(positional);
         return { id: positional };
     }
     if (flags.side)
         return { id: flags["dry-run"] ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
+    const template = ctx.projectConfig?.config.git?.branchNameTemplate;
+    const detection = detectTicketFromBranch(ctx.cwd, pattern, template);
+    if (detection.kind === "detected") {
+        validateTicketId(detection.id);
+        return detection;
+    }
     if (pattern === undefined)
         return deduceTicketFromExisting(ctx.cwd, { sideAllowed: !flags.catchup });
-    const deduced = deduceTicketFromBranch(ctx.cwd, pattern);
-    validateTicketId(deduced.id, pattern);
-    return deduced;
+    if (detection.kind === "noBranch")
+        throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
+    const templateDetail = template?.includes("{TICKET_ID}") ? ` and template "${template}"` : "";
+    throw new CliError(`Cannot deduce a ticket id from branch "${detection.branch}" with pattern "${pattern}"${templateDetail}.`);
 }
 function resolveTicket(ctx, options) {
     if (options.side && !options.dryRun)

package/dist/conventions.js

@@ -18,8 +18,8 @@ export function renderConventions(ctx) {
 function renderTicketIds(ctx) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
     if (pattern === undefined)
-        return "Ticket IDs: no configured format; ask the user for the ID. Without an external ticket, use the next `side-N`.";
-    return `Ticket IDs: \`${pattern}\`; infer a matching ID from the branch. Without an external ticket, use the next \`side-N\`.`;
+        return "Ticket IDs: no configured format; ask the user for the ID. Without a ticket, or when the user asks for a side ticket, use the next `side-N`.";
+    return `Ticket IDs: \`${pattern}\`; infer a matching ID from the branch. Without a ticket, or when the user asks for a side ticket, use the next \`side-N\`.`;
 }
 function renderBranchNames(ctx) {
     const template = ctx.projectConfig?.config.git?.branchNameTemplate;
@@ -50,10 +50,10 @@ 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}\`)`;
+        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`, a separate git repository)`;
         const base = mode.kind === "shared"
-            ? `Plans: use \`.plans\`${sharedFolder}; keep it out of product commits, and run \`${ctx.form} sync\` after changes.`
-            : "Plans: use `.plans`; keep it out of product commits.";
+            ? `Plans: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
+            : "Plans: use `.plans`.";
         const archival = ctx.projectConfig?.config.plans?.autoArchive === true
             ? " Automatic archival is enabled."
             : "";

package/dist/plans/ticket.d.ts

@@ -37,11 +37,10 @@ export interface NextFilePosition {
 export declare function nextFilePosition(entries: readonly string[], newCycle: boolean): NextFilePosition;
 export declare function listEntries(dir: string): TicketEntry[];
 export declare function isPathSafeTicketId(id: string): boolean;
-export declare function validateTicketId(id: string, pattern?: string): void;
-export declare function detectTicketFromBranch(cwd: string, pattern: string): TicketDetection;
+export declare function validateTicketId(id: string): void;
+export declare function detectTicketFromBranch(cwd: string, pattern?: string, template?: string): TicketDetection;
 export interface DeduceFromExistingOptions {
     sideAllowed: boolean;
 }
 /** Without a ticket id pattern, the branch can still name an existing ticket directory. */
 export declare function deduceTicketFromExisting(cwd: string, { sideAllowed }: DeduceFromExistingOptions): DeducedTicket;
-export declare function deduceTicketFromBranch(cwd: string, pattern: string): DeducedTicket;

package/dist/plans/ticket.js

@@ -7,9 +7,10 @@ import { gitOutputOrUndefined } from "../git.js";
 import { archivesDir, isTicketName, plansDir } from "./layout.js";
 const FILE_PREFIX = /^([A-Z])(\d+)-/;
 const SIDE_TICKET = /^side-(\d+)$/;
+const BRANCH_SEPARATORS = "[/_.-]";
+const SIDE_TICKET_BRANCH = new RegExp(`^side-\\d+(?=$|${BRANCH_SEPARATORS})`);
 const PATH_SAFE_TICKET = /^[A-Za-z0-9._-]+$/;
 const ENTRY_ORDER = new Intl.Collator("en", { numeric: true });
-const BRANCH_SEPARATORS = "[/_.-]";
 const LISTED_TICKETS = 10;
 export function resolveTicketDir(cwd, id, { dryRun }) {
     const dir = join(plansDir(cwd), id);
@@ -104,22 +105,49 @@ function statOrLink(path) {
 export function isPathSafeTicketId(id) {
     return id !== "." && !id.includes("..") && PATH_SAFE_TICKET.test(id);
 }
-export function validateTicketId(id, pattern) {
+export function validateTicketId(id) {
     if (!isPathSafeTicketId(id) || !isTicketName(id))
         throw new CliError(`Invalid ticket id: ${id}`);
-    if (pattern !== undefined && !new RegExp(pattern).test(id) && !SIDE_TICKET.test(id))
-        throw new CliError(`Ticket id "${id}" does not match ticketIdPattern "${pattern}".`);
 }
-export function detectTicketFromBranch(cwd, pattern) {
+export function detectTicketFromBranch(cwd, pattern, template) {
     const branch = currentBranch(cwd);
     if (branch === undefined)
         return { kind: "noBranch" };
-    const unanchored = pattern.replace(/^\^/, "").replace(/\$$/, "");
-    const match = new RegExp(unanchored).exec(branch);
+    const sideTicket = SIDE_TICKET_BRANCH.exec(branch);
+    if (sideTicket)
+        return { kind: "detected", id: sideTicket[0], branch };
+    if (pattern === undefined)
+        return { kind: "noMatch", branch };
+    if (template?.includes("{TICKET_ID}")) {
+        const match = branchPatternFromTemplate(template, unanchorPattern(pattern)).exec(branch);
+        const id = match?.[1];
+        if (id === undefined || !isPathSafeTicketId(id) || !isTicketName(id))
+            return { kind: "noMatch", branch };
+        return { kind: "detected", id, branch };
+    }
+    const match = new RegExp(unanchorPattern(pattern)).exec(branch);
     if (!match)
         return { kind: "noMatch", branch };
     return { kind: "detected", id: match[0], branch };
 }
+function unanchorPattern(pattern) {
+    return pattern.replace(/^\^/, "").replace(/\$$/, "");
+}
+function branchPatternFromTemplate(template, ticketPattern) {
+    const placeholder = /\{[^{}]+\}/g;
+    let source = "";
+    let cursor = 0;
+    for (const match of template.matchAll(placeholder)) {
+        source += escapeRegexLiteral(template.slice(cursor, match.index));
+        source += match[0] === "{TICKET_ID}" ? `((?:${ticketPattern})|side-\\d+)` : ".+";
+        cursor = match.index + match[0].length;
+    }
+    source += escapeRegexLiteral(template.slice(cursor));
+    return new RegExp(`^${source}$`);
+}
+function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function currentBranch(cwd) {
     const branch = gitOutputOrUndefined(cwd, "branch", "--show-current");
     return branch === undefined || branch === "" ? undefined : branch;
@@ -157,7 +185,7 @@ function newestModification(dir) {
     return new Date(Math.max(...entries.map((entry) => entry.modifiedAt.getTime())));
 }
 function branchNamesTicket(branch, id) {
-    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escaped = escapeRegexLiteral(id);
     return new RegExp(`(^|${BRANCH_SEPARATORS})${escaped}($|${BRANCH_SEPARATORS})`).test(branch);
 }
 function renderMissingTicketId(tickets, sideAllowed) {
@@ -175,11 +203,3 @@ function renderMissingTicketId(tickets, sideAllowed) {
         lines.push(`  … ${rest} more`);
     return `No ticket id given. Existing tickets:\n${lines.join("\n")}\n${hint}`;
 }
-export function deduceTicketFromBranch(cwd, pattern) {
-    const result = detectTicketFromBranch(cwd, pattern);
-    if (result.kind === "noBranch")
-        throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
-    if (result.kind === "noMatch")
-        throw new CliError(`Cannot deduce a ticket id from branch "${result.branch}" with pattern "${pattern}".`);
-    return result;
-}

package/package.json

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

package/templates/guide/core.md

@@ -2,7 +2,7 @@
 
 ## Ticket Directory
 
-TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID is the external ticket ID or `side-N` for work without an external ticket.
+TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID is the external ticket ID, or `side-N` for a side ticket: work without a ticket.
 
 {{TICKET_DETECTION}}
 
@@ -10,7 +10,7 @@ TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID
 
 {{PLANS_STATE}}
 
-When the user says there is no external ticket, run `{{CMD}} ticket --side` and use the returned TICKET_ID in subsequent ticket commands. Reuse an existing `side-N` directory when the user refers to earlier work. Omit the ticket ID from commit messages.
+When the user says there is no ticket or asks for a side ticket, run `{{CMD}} ticket --side` and use the returned TICKET_ID in subsequent ticket commands. Reuse an existing `side-N` directory when the user refers to earlier work. Omit the ticket ID from commit messages.
 
 ## Work Files
 

package/templates/guide/protocols/aad.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ---
 

package/templates/guide/protocols/description.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ## Steps
 

package/templates/guide/protocols/merge.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ---
 
@@ -24,14 +24,18 @@ Run `{{TICKET_CMD}} --next merge.summary.md` to continue the current cycle. Appe
 
 Resolve the conflicts properly — preserve both intents whenever possible. Do not blindly accept one side.
 
+Resolve conflicts one at a time. Avoid batch processing, broad search-and-replace operations, and other brute-force edits.
+
 **Special case for lock files:** If a lock file has conflicts:
 
 1. Accept all the changes from the incoming branch.
 2. After all other conflicts are resolved, run the proper install command so the package manager re-applies the current branch's dependency changes.
 
-## 4. Finalize the Merge
+## 4. Validate and Commit
+
+After resolving all conflicts, run the codebase's usual checks, such as compilation, linting, and unit tests. Commit the merge as soon as the available checks pass, using Git's default message (for example, `git commit --no-edit`).
 
-Finalize the merge using git's default commit message (e.g. `git commit --no-edit`). Do not write your own commit message — git has already prepared the proper merge message.
+If you need to execute the project, whether through E2E tests or manual checks, do so after the merge commit. Commit any resulting fixes separately.
 
 ## 5. Summarize
 

package/templates/guide/protocols/plan.md

@@ -6,7 +6,7 @@
 
 You need:
 
-- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` for a side ticket, when there is no ticket)
 - a **spec file** in the TICKET_DIR
 
 Identify TICKET_DIR and the spec file before starting the protocol. If either is missing, STOP AND ASK THE USER.

package/templates/guide/protocols/review.md

@@ -4,7 +4,7 @@
 
 You need:
 
-- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` for a side ticket, when there is no ticket)
 - {{BASE_BRANCH_RULE}}
 
 Identify TICKET_DIR and the base branch before starting the protocol.

package/templates/guide/protocols/spec.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ## Phases