alignfirst 0.1.0-beta.0 → 0.1.0-beta.2

package/dist/skills.js

@@ -1,7 +1,5 @@
-import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { CliError } from "./cli-error.js";
 export const STUB_SKILLS = [
     "alignfirst",
     "alspec",
@@ -33,22 +31,3 @@ function readSkillVersion(path) {
         return;
     return /^\s+version:\s*"?([^"\r\n]+)"?\s*$/m.exec(metadata)?.[1]?.trim();
 }
-export function installStubSkills(ctx, agents) {
-    const skillArgs = STUB_SKILLS.flatMap((skill) => ["--skill", skill]);
-    const agentArgs = agents.flatMap((agent) => ["--agent", agent]);
-    try {
-        execFileSync("npx", [
-            "-y",
-            "skills",
-            "add",
-            "https://github.com/paleo/alignfirst",
-            "--global",
-            "--yes",
-            ...skillArgs,
-            ...agentArgs,
-        ], { cwd: ctx.cwd, env: ctx.env, stdio: "inherit" });
-    }
-    catch {
-        throw new CliError("Failed to install the AlignFirst skills globally.");
-    }
-}

package/dist/version-guard.d.ts

@@ -3,6 +3,5 @@ export interface CliRangeResult {
     range: string;
     satisfied: boolean;
 }
-export declare function defaultCliRange(version: string): string;
 export declare function checkCliRange(config: ProjectConfig | undefined, installedVersion: string, commandArgs: string[]): void;
 export declare function cliRangeResult(config: ProjectConfig | undefined, installedVersion: string): CliRangeResult | undefined;

package/dist/version-guard.js

@@ -1,12 +1,5 @@
 import semver from "semver";
 import { CliError } from "./cli-error.js";
-export function defaultCliRange(version) {
-    const parsed = semver.parse(version);
-    if (parsed === null)
-        throw new Error(`Invalid installed version: ${version}`);
-    const upper = parsed.major === 0 ? `0.${parsed.minor + 1}.0` : `${parsed.major + 1}.0.0`;
-    return `>=${version} <${upper}`;
-}
 export function checkCliRange(config, installedVersion, commandArgs) {
     const result = cliRangeResult(config, installedVersion);
     if (result === undefined || result.satisfied)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, plans and docs in one command.",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@paleo/docmap": "~0.9.1",
+    "@paleo/docmap": "~0.10.0-beta.0",
     "arktype": "^2.2.3",
     "semver": "^7.8.5"
   },

package/templates/guide/core.md

@@ -14,9 +14,11 @@ An agent that does not know which protocol to use runs `{{CMD}} guide overview`.
 
 ## TASK_DIR Location
 
-**TASK_DIR** is `.plans/{TICKET_ID}/`. Run `{{CMD}} ticket <id>` and use the directory it prints. The command creates a missing directory, restores an archived one, and lists its entries.
+TASK_DIR holds the work files of a ticket. `{{TICKET_CMD}}` prints it and lists its entries; it creates a missing directory and restores an archived one.
 
-{{TICKET_ID_RULE}}
+{{TICKET_CONTEXT}}
+
+{{PLANS_STATE}}
 
 **Work without a ticket:** when the user says there is no ticket, run `{{CMD}} ticket --side`. Reuse an existing `side-N` directory when the user refers to that earlier work. Omit the ticket ID from commit messages.
 
@@ -36,18 +38,16 @@ Format: `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`
 **Example structure:**
 
 ```text
-.plans/
-├── 123/
-│   ├── A1-spec.md
-│   ├── A2-plan.md
-│   └── A3-AAD.summary.md
-│   └── B1-spec.md
+A1-spec.md
+A2-plan.md
+A3-AAD.summary.md
+B1-spec.md
 ```
 
 ## Notes
 
 - **TICKET_ID** is a unique identifier for the task, often an issue or ticket number.
-- `{{CMD}} ticket <id> --next <filename>` prints the next filename in the current cycle, the extension included (`--next spec.md` giving `.plans/123/A2-spec.md`).
+- `{{TICKET_CMD}} --next <filename>` prints the path of the next file in the current cycle, the extension included (`--next spec.md` giving `A2-spec.md`).
 - `--new-cycle` starts a new cycle.
 - The protocol or the user decides whether to continue the current cycle or start a new one.
 - Cycle letters and file numbers are internal. Never discuss them with the user.

package/templates/guide/protocols/aad.md

@@ -4,8 +4,8 @@
 
 You need:
 
-- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{CMD}} ticket <id> --next AAD.summary.md` prints the file to create
+- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{TICKET_CMD}} --next AAD.summary.md` prints the file to create
 
 Identify and state these values before starting the protocol.
 
@@ -54,7 +54,7 @@ Use subagents (your subagent tool) for distinct, isolated units of work when ben
 
 Finalize the summary file: replace the working notes with the final content described below.
 
-Start the summary with a header, then a suggested commit message (follow the convention you are aware of, or default to `<type>: [<ticket_id>] very short description`). The shorter the better. Omit any field with nothing to list. Always exclude `alignfirst` from skills.
+Start the summary with a header, then a suggested commit message {{COMMIT_RULE}}. The shorter the better. Omit any field with nothing to list. Always exclude `alignfirst` from skills.
 
 Example:
 

package/templates/guide/protocols/catchup.md

@@ -2,7 +2,7 @@
 
 ## Pre-requisites
 
-You need the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket).
+You need the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket).
 
 ## Steps
 

package/templates/guide/protocols/description.md

@@ -4,8 +4,8 @@
 
 You need:
 
-- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{CMD}} ticket <id> --next description.md --new-cycle` prints the file to create
+- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{TICKET_CMD}} --next description.md --new-cycle` prints the file to create
 
 Identify and state these values before starting the protocol.
 
@@ -29,7 +29,7 @@ Identify and state these values before starting the protocol.
 [description body]
 ```
 
-Start with a suggested commit message (follow the convention you are aware of, or default to `<type>: [<ticket_id>] very short description`). Refine it from the suggested commit messages found in the specs and summaries you read. Keep it brief—usually 3-5 words for the description part. Shorter is better when it's clear.
+Start with a suggested commit message {{COMMIT_RULE}}. Refine it from the suggested commit messages found in the specs and summaries you read. Keep it brief—usually 3-5 words for the description part. Shorter is better when it's clear.
 
 ## Guidelines for the Description Body
 

package/templates/guide/protocols/merge.md

@@ -4,8 +4,8 @@
 
 You need:
 
-- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{CMD}} ticket <id> --next merge.summary.md` prints the file to create
+- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{TICKET_CMD}} --next merge.summary.md` prints the file to create
 
 Identify and state these values before starting the protocol.
 
@@ -17,7 +17,7 @@ This protocol applies when a merge or rebase has produced conflicts, or when the
 
 Run `git status` to check for conflicts.
 
-**If there are no conflicts:** start the merge — use the incoming branch if the user provided one, otherwise ask which branch to merge. If the merge completes cleanly, you are done — no summary file needed. Otherwise, continue with the steps below.
+**If there are no conflicts:** start the merge — use the incoming branch if the user provided one, {{BASE_BRANCH_RULE}} If the merge completes cleanly, you are done — no summary file needed. Otherwise, continue with the steps below.
 
 ## 2. Investigate
 

package/templates/guide/protocols/plan.md

@@ -6,8 +6,8 @@
 
 You need:
 
-- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{CMD}} ticket <id> --next plan.md` or `{{CMD}} ticket <id> --next main-plan.md` prints the file to create
+- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{TICKET_CMD}} --next plan.md` or `{{TICKET_CMD}} --next main-plan.md` prints the file to create
 - a **spec file** in the TASK_DIR
 
 Identify and state these values before starting the protocol. If any of these pieces of information is missing, STOP AND ASK THE USER.
@@ -210,7 +210,7 @@ Note:
 
 Write the plan file(s) according to the determined structure:
 
-Use `{{CMD}} ticket <id> --next plan.md`, `{{CMD}} ticket <id> --next main-plan.md`, or `{{CMD}} ticket <id> --next plan-<descriptor>.md` to get the next number. Run one command per file.
+Use `{{TICKET_CMD}} --next plan.md`, `{{TICKET_CMD}} --next main-plan.md`, or `{{TICKET_CMD}} --next plan-<descriptor>.md` to get the next number. Run one command per file.
 
 **Single Plan**:
 

package/templates/guide/protocols/review.md

@@ -4,9 +4,9 @@
 
 You need:
 
-- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{CMD}} ticket <id> --next review.md --new-cycle` prints the file to create
-- the **base branch** to compare against - use the branch provided by the user, or fall back to the default branch.
+- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{TICKET_CMD}} --next review.md --new-cycle` prints the file to create
+- {{BASE_BRANCH_RULE}}
 
 Identify and state these values before starting the protocol.
 

package/templates/guide/protocols/spec.md

@@ -4,8 +4,8 @@
 
 You need:
 
-- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{CMD}} ticket <id> --next spec.md --new-cycle` prints the file to create
+- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{TICKET_CMD}} --next spec.md --new-cycle` prints the file to create
 
 Identify and state these values before starting the protocol.
 
@@ -51,7 +51,7 @@ Do not use your question tool. Always ask in plain text. Your questions will be
 
 After the user approves your proposal, write the specification in a markdown file in TASK_DIR. Compose the filename with the current CYCLE_LETTER and the next FILE_NUMBER, e.g. `A1-spec.md`. Do not overwrite an existing file.
 
-- After the title, include a suggested commit message (follow the convention you are aware of, or default to `<type>: [<ticket_id>] very short description`). The shorter the better. Then list the required documentation and skills. List each doc file individually — never a folder. Always exclude `alignfirst` from skills. Omit any field with nothing to list. Example:
+- After the title, include a suggested commit message {{COMMIT_RULE}}. The shorter the better. Then list the required documentation and skills. List each doc file individually — never a folder. Always exclude `alignfirst` from skills. Omit any field with nothing to list. Example:
 
   ```text
   # [{TICKET_ID}] Short Title

package/dist/commands/developers.d.ts

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

package/dist/commands/developers.js

@@ -1,36 +0,0 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { parseArgs } from "node:util";
-import { CliError } from "../cli-error.js";
-import { resolveProjectFile } from "../overlay.js";
-import { parseCommandArgs } from "../parse-args.js";
-export function runDevelopers(ctx, args) {
-    const usage = `Usage: ${ctx.form} DEVELOPERS.md\n`;
-    if (parseDevelopersArgs(ctx, args, usage))
-        return 0;
-    const file = resolveProjectFile(ctx.cwd, ctx.overlay, "DEVELOPERS.md");
-    if (file === undefined)
-        throw missingDevelopersError(ctx);
-    ctx.stdout.write(readFileSync(file.path, "utf-8"));
-    return 0;
-}
-function parseDevelopersArgs(ctx, args, usage) {
-    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
-        args,
-        options: { help: { type: "boolean", short: "h", default: false } },
-        strict: true,
-        allowPositionals: true,
-    }));
-    if (positionals.length > 0)
-        throw new CliError(`Unexpected argument: ${positionals[0]}\n\n${usage}`);
-    if (!values.help)
-        return false;
-    ctx.stdout.write(usage);
-    return true;
-}
-function missingDevelopersError(ctx) {
-    const tried = [join(ctx.cwd, "DEVELOPERS.md")];
-    if (ctx.overlay !== undefined)
-        tried.push(join(ctx.overlay.dir, "DEVELOPERS.md"));
-    return new CliError(`No DEVELOPERS.md found. Tried: ${tried.join(", ")}.`);
-}

package/dist/commands/setup.d.ts

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

package/dist/commands/setup.js

@@ -1,254 +0,0 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
-import { basename, join } from "node:path";
-import { parseArgs } from "node:util";
-import { CliError } from "../cli-error.js";
-import { assertMainWorktreeRoot, gitOutputOrUndefined, gitSucceeds } from "../git.js";
-import { normalizeRemoteUrl } from "../overlay.js";
-import { parseCommandArgs } from "../parse-args.js";
-import { linkPlans } from "../plans/link.js";
-import { PROJECT_CONFIG_FILENAME, readProjectConfig, validateProjectConfig, } from "../project-config.js";
-import { installStubSkills } from "../skills.js";
-import { defaultCliRange } from "../version-guard.js";
-const ADOPT_FILES = ["AGENTS.md", "DEVELOPERS.md", "docs"];
-export function runSetup(ctx, args) {
-    const usage = setupUsage(ctx);
-    const options = parseSetupArgs(ctx, args, usage);
-    if (options === undefined)
-        return 0;
-    if (options.overlay)
-        return runOverlaySetup(ctx, options);
-    if (options.adopt)
-        return runAdopt(ctx);
-    return runDefaultSetup(ctx, options);
-}
-function setupUsage(ctx) {
-    return `Usage:
-  ${ctx.form} setup [--ticket-pattern <regex>] [--plans-folder <name>] [--port-range <first>-<last>] [--agent <name>]...
-  ${ctx.form} setup --overlay [--plans-folder <name>] [--ticket-pattern <regex>] [--port-range <first>-<last>]
-  ${ctx.form} setup --adopt
-`;
-}
-function parseSetupArgs(ctx, args, usage) {
-    const { values } = parseCommandArgs(usage, () => parseArgs({
-        args,
-        options: {
-            "ticket-pattern": { type: "string" },
-            "plans-folder": { type: "string" },
-            "port-range": { type: "string" },
-            agent: { type: "string", multiple: true, default: [] },
-            overlay: { type: "boolean", default: false },
-            adopt: { type: "boolean", default: false },
-            help: { type: "boolean", short: "h", default: false },
-        },
-        strict: true,
-    }));
-    if (values.help) {
-        ctx.stdout.write(usage);
-        return;
-    }
-    if (values.overlay && values.adopt)
-        throw new CliError(`--overlay and --adopt are mutually exclusive.\n\n${usage}`);
-    if ((values.overlay || values.adopt) && values.agent.length > 0)
-        throw new CliError(`--agent is available only in the default setup mode.\n\n${usage}`);
-    const portRange = values["port-range"] === undefined ? undefined : parsePortRange(values["port-range"], usage);
-    const options = {
-        ticketPattern: values["ticket-pattern"],
-        plansFolder: values["plans-folder"],
-        portRange,
-        agents: values.agent,
-        overlay: values.overlay,
-        adopt: values.adopt,
-    };
-    validateSetupOptions(options);
-    return options;
-}
-function parsePortRange(value, usage) {
-    const match = /^(\d+)-(\d+)$/.exec(value);
-    if (!match)
-        throw new CliError(`--port-range must be <first>-<last>.\n\n${usage}`);
-    return { first: Number(match[1]), last: Number(match[2]) };
-}
-function validateSetupOptions(options) {
-    validateProjectConfig({
-        schemaVersion: 1,
-        ...(options.ticketPattern === undefined ? {} : { ticketPattern: options.ticketPattern }),
-        ...(options.plansFolder === undefined ? {} : { plans: { folder: options.plansFolder } }),
-        ...(options.portRange === undefined ? {} : { portRange: options.portRange }),
-    }, PROJECT_CONFIG_FILENAME);
-}
-function runDefaultSetup(ctx, options) {
-    assertMainWorktreeRoot(ctx.cwd);
-    setupProjectConfig(ctx, options);
-    setupPlansDirectory(ctx);
-    installStubSkills(ctx, options.agents);
-    ctx.stdout.write("Installed the AlignFirst skills globally.\n");
-    setupReadme(ctx);
-    return 0;
-}
-function setupProjectConfig(ctx, options) {
-    const path = join(ctx.cwd, PROJECT_CONFIG_FILENAME);
-    if (existsSync(path)) {
-        readProjectConfig(ctx.cwd);
-        ctx.stdout.write(`${PROJECT_CONFIG_FILENAME} is valid.\n`);
-        if (hasProjectOptions(options))
-            throw new CliError(`${PROJECT_CONFIG_FILENAME} exists; edit it instead of passing options.`);
-        return;
-    }
-    const cli = defaultCliRange(ctx.version);
-    const config = validateProjectConfig({
-        schemaVersion: 1,
-        cli,
-        ...(options.ticketPattern === undefined ? {} : { ticketPattern: options.ticketPattern }),
-        ...(options.plansFolder === undefined ? {} : { plans: { folder: options.plansFolder } }),
-        ...(options.portRange === undefined ? {} : { portRange: options.portRange }),
-    }, PROJECT_CONFIG_FILENAME);
-    writeJson(path, config);
-    ctx.stdout.write(`Created ${PROJECT_CONFIG_FILENAME} (cli ${cli})\n`);
-}
-function hasProjectOptions(options) {
-    return (options.ticketPattern !== undefined ||
-        options.plansFolder !== undefined ||
-        options.portRange !== undefined);
-}
-function setupPlansDirectory(ctx) {
-    const plansPath = join(ctx.cwd, ".plans");
-    if (!existsSync(plansPath)) {
-        mkdirSync(plansPath);
-        ctx.stdout.write("Created .plans/\n");
-    }
-    if (gitSucceeds(ctx.cwd, "check-ignore", "-q", ".plans"))
-        return;
-    appendLine(join(ctx.cwd, ".gitignore"), ".plans");
-    ctx.stdout.write("Added .plans to .gitignore.\n");
-}
-function appendLine(path, line) {
-    const content = existsSync(path) ? readFileSync(path, "utf-8") : "";
-    const separator = content === "" || content.endsWith("\n") ? "" : "\n";
-    appendFileSync(path, `${separator}${line}\n`);
-}
-function setupReadme(ctx) {
-    const path = join(ctx.cwd, "README.md");
-    if (!existsSync(path))
-        return;
-    const content = readFileSync(path, "utf-8");
-    if (/alignfirst/i.test(content))
-        return;
-    appendFileSync(path, "\n## Prerequisites\n\nInstall the AlignFirst CLI: `npm install -g alignfirst`.\n");
-    ctx.stdout.write("Added the CLI prerequisite to README.md.\n");
-}
-function runOverlaySetup(ctx, options) {
-    const overlaysDir = resolveOverlaysDir(ctx);
-    assertMainWorktreeRoot(ctx.cwd);
-    const projectPath = realpathSync(ctx.cwd);
-    const name = options.plansFolder ?? basename(projectPath);
-    const overlayDir = join(overlaysDir, name, "_project");
-    if (existsSync(overlayDir))
-        throw new CliError(`${overlayDir} already exists.`);
-    const config = buildOverlayConfig(ctx, options, projectPath);
-    mkdirSync(overlayDir, { recursive: true });
-    writeJson(join(overlayDir, PROJECT_CONFIG_FILENAME), config);
-    ctx.stdout.write(`Created overlay: ${overlayDir}\n`);
-    setupOverlayPlans(ctx, overlaysDir, name);
-    setupGitExclude(ctx);
-    return 0;
-}
-function resolveOverlaysDir(ctx) {
-    const value = ctx.env.ALIGNFIRST_OVERLAYS;
-    if (value === undefined || value === "")
-        throw new CliError("ALIGNFIRST_OVERLAYS is not set.");
-    return value.startsWith("~/") ? join(ctx.home, value.slice(2)) : value;
-}
-function buildOverlayConfig(ctx, options, projectPath) {
-    const origin = gitOutputOrUndefined(ctx.cwd, "remote", "get-url", "origin");
-    return validateProjectConfig({
-        schemaVersion: 1,
-        project: {
-            ...(origin === undefined || origin === "" ? {} : { remote: normalizeRemoteUrl(origin) }),
-            paths: [projectPath],
-        },
-        ...(options.ticketPattern === undefined ? {} : { ticketPattern: options.ticketPattern }),
-        ...(options.plansFolder === undefined ? {} : { plans: { folder: options.plansFolder } }),
-        ...(options.portRange === undefined ? {} : { portRange: options.portRange }),
-    }, PROJECT_CONFIG_FILENAME);
-}
-function setupOverlayPlans(ctx, overlaysDir, name) {
-    if (gitSucceeds(overlaysDir, "rev-parse", "--git-dir")) {
-        linkPlans(ctx, join(overlaysDir, name));
-        return;
-    }
-    const plansPath = join(ctx.cwd, ".plans");
-    if (!existsSync(plansPath))
-        mkdirSync(plansPath);
-    ctx.stdout.write("Using a local .plans directory.\n");
-}
-function setupGitExclude(ctx) {
-    if (gitSucceeds(ctx.cwd, "check-ignore", "-q", ".plans"))
-        return;
-    appendLine(join(ctx.cwd, ".git", "info", "exclude"), ".plans");
-    ctx.stdout.write("Added .plans to .git/info/exclude.\n");
-}
-function runAdopt(ctx) {
-    const overlay = ctx.overlay;
-    if (overlay === undefined) {
-        const value = ctx.env.ALIGNFIRST_OVERLAYS;
-        throw new CliError(`No overlay matches this repository (ALIGNFIRST_OVERLAYS=${value === undefined || value === "" ? "unset" : value}).`);
-    }
-    adoptConfig(ctx, overlay.dir, overlay.config);
-    const agentsConflict = adoptFiles(ctx, overlay.dir);
-    removePlansExclude(ctx);
-    if (readdirSync(overlay.dir).length === 0)
-        rmdirSync(overlay.dir);
-    else
-        ctx.stdout.write(`Overlay remains: ${overlay.dir}\n`);
-    ctx.stdout.write("Next: add .plans to .gitignore.\n");
-    if (agentsConflict)
-        ctx.stdout.write("Next: merge the overlay AGENTS.md conventions by hand.\n");
-    return 0;
-}
-function adoptConfig(ctx, overlayDir, config) {
-    const name = PROJECT_CONFIG_FILENAME;
-    const source = join(overlayDir, name);
-    const target = join(ctx.cwd, name);
-    if (existsSync(target)) {
-        ctx.stdout.write(`kept in the overlay: ${name} (the root has its own)\n`);
-        return;
-    }
-    const rootConfig = structuredClone(config);
-    delete rootConfig.project;
-    writeJson(target, validateProjectConfig(rootConfig, name));
-    unlinkSync(source);
-    ctx.stdout.write(`Adopted ${name}.\n`);
-}
-function adoptFiles(ctx, overlayDir) {
-    let agentsConflict = false;
-    for (const name of ADOPT_FILES) {
-        const source = join(overlayDir, name);
-        if (!existsSync(source))
-            continue;
-        const target = join(ctx.cwd, name);
-        if (existsSync(target)) {
-            ctx.stdout.write(`kept in the overlay: ${name} (the root has its own)\n`);
-            if (name === "AGENTS.md")
-                agentsConflict = true;
-            continue;
-        }
-        renameSync(source, target);
-        ctx.stdout.write(`Adopted ${name}.\n`);
-    }
-    return agentsConflict;
-}
-function removePlansExclude(ctx) {
-    const path = join(ctx.cwd, ".git", "info", "exclude");
-    if (!existsSync(path))
-        return;
-    const content = readFileSync(path, "utf-8");
-    const lines = content.split(/\r?\n/);
-    const filtered = lines.filter((line) => line.trim() !== ".plans");
-    if (filtered.length === lines.length)
-        return;
-    writeFileSync(path, filtered.join("\n"));
-    ctx.stdout.write("Removed .plans from .git/info/exclude.\n");
-}
-function writeJson(path, value) {
-    writeFileSync(path, `${JSON.stringify(value, undefined, 2)}\n`);
-}

package/dist/overlay.d.ts

@@ -1,19 +0,0 @@
-import { type ProjectConfig } from "./project-config.js";
-export interface Overlay {
-    dir: string;
-    config: ProjectConfig;
-    matchedBy: "remote" | "paths";
-}
-export interface ProjectFile {
-    path: string;
-    source: "root" | "overlay";
-}
-export interface ResolvedProjectConfig {
-    config: ProjectConfig;
-    source: "root" | "overlay";
-    overlay?: Overlay;
-}
-export declare function findOverlay(cwd: string, env: NodeJS.ProcessEnv, home: string): Overlay | undefined;
-export declare function normalizeRemoteUrl(url: string): string;
-export declare function resolveProjectFile(cwd: string, overlay: Overlay | undefined, name: string): ProjectFile | undefined;
-export declare function resolveProjectConfig(cwd: string, env: NodeJS.ProcessEnv, home: string): ResolvedProjectConfig | undefined;

package/dist/overlay.js

@@ -1,83 +0,0 @@
-import { existsSync, readdirSync, realpathSync } from "node:fs";
-import { join } from "node:path";
-import { CliError } from "./cli-error.js";
-import { gitOutputOrUndefined } from "./git.js";
-import { readProjectConfig } from "./project-config.js";
-export function findOverlay(cwd, env, home) {
-    const configuredDir = env.ALIGNFIRST_OVERLAYS;
-    if (configuredDir === undefined || configuredDir === "")
-        return;
-    const overlaysDir = expandHome(configuredDir, home);
-    const candidates = readOverlayCandidates(overlaysDir);
-    const origin = gitOutputOrUndefined(cwd, "remote", "get-url", "origin");
-    const normalizedOrigin = origin === undefined || origin === "" ? undefined : normalizeRemoteUrl(origin);
-    const realCwd = realpathSync(cwd);
-    const remoteMatches = candidates.filter(({ config }) => normalizedOrigin !== undefined && config.project?.remote === normalizedOrigin);
-    if (remoteMatches.length > 0)
-        return selectOverlay(remoteMatches, "remote");
-    const pathMatches = candidates.filter(({ config }) => config.project?.paths?.includes(realCwd));
-    if (pathMatches.length > 0)
-        return selectOverlay(pathMatches, "paths");
-    return;
-}
-function expandHome(path, home) {
-    return path.startsWith("~/") ? join(home, path.slice(2)) : path;
-}
-function readOverlayCandidates(overlaysDir) {
-    if (!existsSync(overlaysDir))
-        return [];
-    return readdirSync(overlaysDir, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .flatMap((entry) => {
-        const dir = join(overlaysDir, entry.name, "_project");
-        const config = readProjectConfig(dir);
-        return config === undefined ? [] : [{ dir, config }];
-    });
-}
-function selectOverlay(candidates, matchedBy) {
-    if (candidates.length > 1)
-        throw new CliError(`Multiple AlignFirst overlays match this project: ${candidates
-            .map(({ dir }) => dir)
-            .join(", ")}`);
-    const candidate = candidates[0];
-    return { ...candidate, matchedBy };
-}
-export function normalizeRemoteUrl(url) {
-    const value = url
-        .trim()
-        .replace(/\/+$/, "")
-        .replace(/\.git$/, "");
-    const scpMatch = value.includes("://") ? null : /^(?:[^@]+@)?([^:/]+):(.+)$/.exec(value);
-    if (scpMatch)
-        return `${scpMatch[1].toLowerCase()}/${scpMatch[2].replace(/^\/+/, "")}`;
-    try {
-        const parsed = new URL(value.includes("://") ? value : `https://${value}`);
-        return `${parsed.hostname.toLowerCase()}${parsed.pathname}`
-            .replace(/\/+$/, "")
-            .replace(/\.git$/, "")
-            .replace(/^\/+/, "");
-    }
-    catch {
-        return value;
-    }
-}
-export function resolveProjectFile(cwd, overlay, name) {
-    const rootPath = join(cwd, name);
-    if (existsSync(rootPath))
-        return { path: rootPath, source: "root" };
-    if (overlay === undefined)
-        return;
-    const overlayPath = join(overlay.dir, name);
-    if (existsSync(overlayPath))
-        return { path: overlayPath, source: "overlay" };
-    return;
-}
-export function resolveProjectConfig(cwd, env, home) {
-    const overlay = findOverlay(cwd, env, home);
-    const rootConfig = readProjectConfig(cwd);
-    if (rootConfig !== undefined)
-        return { config: rootConfig, source: "root", overlay };
-    if (overlay !== undefined)
-        return { config: overlay.config, source: "overlay", overlay };
-    return;
-}