aligndev 0.0.0 → 0.18.0

package/dist/project/ports.js

@@ -0,0 +1,55 @@
+import { formatRange } from "./format.js";
+import { MARKER_FILENAME } from "./markers.js";
+export function findFreeBlock(inventory, size, code) {
+    const rootRanges = inventory.directories.find(({ path }) => path === inventory.root)?.portRanges;
+    const markerPath = `${inventory.root}/${MARKER_FILENAME}`;
+    if (rootRanges === undefined)
+        throw new Error(`${markerPath} has no portRanges.`);
+    const rootRange = selectPortRange(rootRanges, code, markerPath);
+    const occupied = [
+        ...inventory.projects.flatMap(({ portRange }) => portRange === undefined ? [] : [allocatedRange(portRange)]),
+        ...inventory.directories.flatMap(({ path, portRanges }) => path === inventory.root
+            ? []
+            : (portRanges ?? []).map((portRange) => allocatedRange(portRange))),
+    ];
+    const first = lowestFreeBase(occupied, size, rootRange.first, rootRange.last);
+    if (first === undefined) {
+        throw new Error(`No block of ${size} contiguous free ports in ${formatRange(rootRange)}.`);
+    }
+    return { first, last: first + size - 1 };
+}
+function selectPortRange(ranges, code, markerPath) {
+    const declaredCodes = ranges.flatMap((range) => (range.code === undefined ? [] : [range.code]));
+    if (code !== undefined) {
+        const selected = ranges.find((range) => range.code === code);
+        if (selected !== undefined)
+            return selected;
+        throw new Error(`Unknown port range code ${JSON.stringify(code)} in ${markerPath}; ` +
+            `declared codes: ${declaredCodes.join(", ")}`);
+    }
+    const defaultRange = ranges.find((range) => range.code === undefined);
+    if (defaultRange !== undefined)
+        return defaultRange;
+    throw new Error(`${markerPath} declares no default range: pass --range <code> ` +
+        `(codes: ${declaredCodes.join(", ")})`);
+}
+function lowestFreeBase(ranges, size, firstPort, lastPort) {
+    let candidate = firstPort;
+    for (const range of ranges.toSorted((left, right) => left.start - right.start)) {
+        if (range.end < candidate)
+            continue;
+        if (range.start > lastPort)
+            break;
+        if (fitsBefore(candidate, size, range.start - 1))
+            return candidate;
+        candidate = Math.max(candidate, range.end + 1);
+    }
+    return fitsBefore(candidate, size, lastPort) ? candidate : undefined;
+}
+function fitsBefore(basePort, size, lastPort) {
+    const end = basePort + size - 1;
+    return Number.isSafeInteger(end) && end <= lastPort;
+}
+function allocatedRange(range) {
+    return { start: range.first, end: range.last };
+}

package/dist/project/project-cli.d.ts

@@ -0,0 +1,17 @@
+import type { CommandForms } from "../command-form.js";
+import type { AligndevConfig, ProjectsRoot } from "../config.js";
+import type { Output } from "../output.js";
+export interface ProjectsCallerContext {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    home: string;
+    stdout: Output;
+    stderr: Output;
+    forms: CommandForms;
+    alignfirstCommand: string[];
+}
+export interface ProjectsContext extends ProjectsCallerContext {
+    projectsRoot?: ProjectsRoot;
+}
+export declare function runProject(tokens: string[], config: AligndevConfig | undefined, caller: ProjectsCallerContext): number;
+export declare function renderProjectsGuideForRoot(ctx: ProjectsContext, rootOption: string | undefined): string;

package/dist/project/project-cli.js

@@ -0,0 +1,227 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { errorMessage } from "../errors.js";
+import { buildInventory } from "./discovery.js";
+import { formatRange } from "./format.js";
+import { renderProjectsGuide } from "./guide.js";
+import { assertValidPortRanges, MARKER_FILENAME, readMarker, writeMarker, } from "./markers.js";
+import { findFreeBlock } from "./ports.js";
+import { renderPortRangeJson, renderProjectDoctor, renderProjectDoctorFailure, renderProjectList, renderProjectListJson, renderProjectStatus, renderProjectStatusJson, } from "./render.js";
+import { getProjectStatus } from "./status.js";
+export function runProject(tokens, config, caller) {
+    const ctx = { ...caller, projectsRoot: config?.projectsRoot };
+    try {
+        return runProjectCommand(ctx, parseProjectsArgs(tokens));
+    }
+    catch (error) {
+        ctx.stderr.write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+function runProjectCommand(ctx, args) {
+    if (args.help || args.command === undefined) {
+        ctx.stdout.write(renderUsage(ctx.forms.aligndev));
+        return 0;
+    }
+    if (args.command === "doctor")
+        return inspectProjectInventory(ctx, args.root);
+    const root = resolveProjectsRoot(ctx, args.root);
+    if (args.command === "init")
+        return initializeProjectsDirectory(root, args, ctx.stdout);
+    const marker = requireMarker(root, ctx.forms.aligndev);
+    const inventory = inventoryFor(root, marker, ctx);
+    if (args.command === "list") {
+        ctx.stdout.write(args.json ? renderProjectListJson(inventory) : renderProjectList(inventory));
+        return 0;
+    }
+    if (args.command === "status" && args.path !== undefined) {
+        const details = getProjectStatus(inventory, args.path);
+        ctx.stdout.write(args.json ? renderProjectStatusJson(details) : renderProjectStatus(details));
+        return 0;
+    }
+    if (args.command === "free-ports" && args.size !== undefined) {
+        const range = findFreeBlock(inventory, args.size, args.range);
+        ctx.stdout.write(args.json ? renderPortRangeJson(range) : `${formatRange(range)}\n`);
+        return 0;
+    }
+    throw new Error("Invalid aligndev project command");
+}
+function renderUsage(aligndev) {
+    return `Usage:
+  ${aligndev} project list [--json] [--root <path>]
+  ${aligndev} project doctor [--root <path>]
+  ${aligndev} project status <path> [--json] [--root <path>]
+  ${aligndev} project init [--root <path>] [--description <text>] [--port-range [<code>=]<first>-<last>]...
+  ${aligndev} project free-ports --size <n> [--range <code>] [--json] [--root <path>]
+  ${aligndev} project --help
+
+--root defaults to projectsRoot in the aligndev config, then to the working directory.
+`;
+}
+// The projects guide, followed by the directory sections when the root carries a marker.
+export function renderProjectsGuideForRoot(ctx, rootOption) {
+    const root = resolveProjectsRoot(ctx, rootOption);
+    const marker = readMarker(root);
+    const inventory = marker === undefined ? undefined : inventoryFor(root, marker, ctx);
+    return renderProjectsGuide(ctx.forms, inventory);
+}
+function inspectProjectInventory(ctx, rootOption) {
+    try {
+        const root = resolveProjectsRoot(ctx, rootOption);
+        const inventory = inventoryFor(root, requireMarker(root, ctx.forms.aligndev), ctx);
+        ctx.stdout.write(renderProjectDoctor(inventory));
+        return inventory.issues.length === 0 ? 0 : 1;
+    }
+    catch (error) {
+        ctx.stdout.write(renderProjectDoctorFailure(errorMessage(error)));
+        return 1;
+    }
+}
+function parseProjectsArgs(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: {
+            root: { type: "string" },
+            json: { type: "boolean", default: false },
+            description: { type: "string" },
+            "port-range": { type: "string", multiple: true },
+            range: { type: "string" },
+            size: { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        strict: true,
+        allowPositionals: true,
+    });
+    if (values.help)
+        return emptyModeArgs(values.root, true);
+    const [rawCommand, path, ...extra] = positionals;
+    if (rawCommand === undefined) {
+        assertNoCommandOptions(values);
+        return emptyModeArgs(values.root, false);
+    }
+    if (!isProjectsCommand(rawCommand))
+        throw new Error(`Unknown projects command: ${rawCommand}`);
+    validatePositionals(rawCommand, path, extra);
+    validateOptionPlacement(rawCommand, values);
+    return {
+        command: rawCommand,
+        ...(path === undefined ? {} : { path }),
+        ...(values.root === undefined ? {} : { root: values.root }),
+        json: values.json,
+        help: false,
+        ...(values.description === undefined ? {} : { description: values.description }),
+        ...(values["port-range"] === undefined
+            ? {}
+            : { portRanges: parsePortRanges(values["port-range"]) }),
+        ...(values.range === undefined ? {} : { range: values.range }),
+        ...(values.size === undefined ? {} : { size: parsePositiveInteger("--size", values.size) }),
+    };
+}
+function emptyModeArgs(root, help) {
+    return {
+        ...(root === undefined ? {} : { root }),
+        json: false,
+        help,
+    };
+}
+function assertNoCommandOptions(values) {
+    if (values.json ||
+        values.description !== undefined ||
+        values["port-range"] !== undefined ||
+        values.range !== undefined ||
+        values.size !== undefined) {
+        throw new Error("Command options require a projects command");
+    }
+}
+function isProjectsCommand(value) {
+    return (value === "list" ||
+        value === "doctor" ||
+        value === "status" ||
+        value === "init" ||
+        value === "free-ports");
+}
+function validatePositionals(command, path, extra) {
+    if (command === "status") {
+        if (path === undefined || extra.length > 0)
+            throw new Error("status requires exactly one path");
+        return;
+    }
+    if (path !== undefined)
+        throw new Error(`${command} does not accept a path`);
+}
+function validateOptionPlacement(command, values) {
+    if (values.json && command !== "list" && command !== "status" && command !== "free-ports") {
+        throw new Error("--json is valid only with list, status, or free-ports");
+    }
+    if (command !== "init" &&
+        (values.description !== undefined || values["port-range"] !== undefined)) {
+        throw new Error("--description and --port-range are valid only with init");
+    }
+    if (values.range !== undefined && command !== "free-ports") {
+        throw new Error("--range is valid only with free-ports");
+    }
+    if (command === "free-ports") {
+        if (values.size === undefined)
+            throw new Error("free-ports requires --size <n>");
+    }
+    else if (values.size !== undefined) {
+        throw new Error("--size is valid only with free-ports");
+    }
+}
+function parsePortRanges(values) {
+    const ranges = values.map(parsePortRange);
+    assertValidPortRanges(ranges, "--port-range");
+    return ranges;
+}
+function parsePortRange(value) {
+    const match = /^(?:([a-z][a-z0-9-]*)=)?(\d+)-(\d+)$/u.exec(value);
+    if (match === null)
+        throw new Error("--port-range must be [<code>=]<first>-<last>");
+    return {
+        ...(match[1] === undefined ? {} : { code: match[1] }),
+        first: Number(match[2]),
+        last: Number(match[3]),
+    };
+}
+function parsePositiveInteger(option, value) {
+    if (!/^[1-9]\d*$/u.test(value))
+        throw new Error(`${option} must be a positive integer`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        throw new Error(`${option} must be a positive integer`);
+    return parsed;
+}
+function resolveProjectsRoot(ctx, rootOption) {
+    if (rootOption !== undefined)
+        return realpathSync(resolveRootOption(ctx, rootOption));
+    return realpathSync(ctx.projectsRoot?.path ?? ctx.cwd);
+}
+function resolveRootOption(ctx, rootOption) {
+    const expanded = rootOption.startsWith("~/") ? join(ctx.home, rootOption.slice(2)) : rootOption;
+    return isAbsolute(expanded) ? expanded : resolve(ctx.cwd, expanded);
+}
+function initializeProjectsDirectory(root, args, stdout) {
+    const markerPath = join(root, MARKER_FILENAME);
+    if (readMarker(root) !== undefined)
+        throw new Error(`${markerPath} already exists.`);
+    writeMarker(root, {
+        ...(args.description === undefined ? {} : { description: args.description }),
+        ...(args.portRanges === undefined ? {} : { portRanges: args.portRanges }),
+    });
+    stdout.write(`Created ${markerPath}\n`);
+    return 0;
+}
+function requireMarker(root, aligndev) {
+    const marker = readMarker(root);
+    if (marker !== undefined)
+        return marker;
+    throw new Error(`${root} is not a projects directory: ${MARKER_FILENAME} is missing. ` +
+        `Run \`${aligndev} project init\` there, or pass --root <path>.`);
+}
+function inventoryFor(root, marker, ctx) {
+    return buildInventory(root, marker, {
+        env: ctx.env,
+        alignfirstCommand: ctx.alignfirstCommand,
+    });
+}

package/dist/project/render.d.ts

@@ -0,0 +1,10 @@
+import type { ProjectInventory } from "./discovery.js";
+import type { PortRange } from "./markers.js";
+import type { ProjectDetails } from "./status.js";
+export declare function renderProjectList(inventory: ProjectInventory): string;
+export declare function renderProjectListJson(inventory: ProjectInventory): string;
+export declare function renderProjectDoctor(inventory: ProjectInventory): string;
+export declare function renderProjectDoctorFailure(message: string): string;
+export declare function renderProjectStatus(details: ProjectDetails): string;
+export declare function renderProjectStatusJson(details: ProjectDetails): string;
+export declare function renderPortRangeJson(range: PortRange): string;

package/dist/project/render.js

@@ -0,0 +1,144 @@
+import { escapeAdditionalJsonCharacters, escapeControlCharacters, formatRange } from "./format.js";
+export function renderProjectList(inventory) {
+    const lines = ["Projects:"];
+    if (inventory.projects.length === 0)
+        lines.push("  (none)");
+    for (const project of inventory.projects) {
+        lines.push(`- Name: ${renderOutputValue(project.name)}`, `  Path: ${renderOutputValue(project.path)}`, `  Directory: ${renderOutputValue(project.directory)}`, `  Port range: ${renderProjectRange(project.portRange, project.portRangeCode)}`, `  Workspaces: ${renderValues(project.workspaces)}`);
+    }
+    lines.push("", "Directories:");
+    if (inventory.directories.length === 0)
+        lines.push("  (none)");
+    for (const directory of inventory.directories) {
+        lines.push(`- Path: ${renderOutputValue(directory.path)}`);
+        if (directory.description !== undefined) {
+            lines.push(`  Description: ${renderOutputValue(directory.description)}`);
+        }
+        if (directory.portRanges === undefined)
+            lines.push("  Port ranges: (none)");
+        else {
+            lines.push("  Port ranges:");
+            for (const range of directory.portRanges)
+                lines.push(`    ${renderMarkerRange(range)}`);
+        }
+        lines.push(`  Others: ${renderValues(directory.others)}`);
+    }
+    lines.push("", "Issues:");
+    if (inventory.issues.length === 0)
+        lines.push("  (none)");
+    for (const issue of inventory.issues) {
+        lines.push(`- ${renderOutputValue(issue.path)}: ${escapeControlCharacters(issue.message)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function renderProjectListJson(inventory) {
+    const report = {
+        root: inventory.root,
+        directories: inventory.directories.map((directory) => ({
+            path: directory.path,
+            description: directory.description ?? null,
+            portRanges: directory.portRanges ?? [],
+            others: directory.others,
+        })),
+        projects: inventory.projects.map((project) => ({
+            name: project.name,
+            path: project.path,
+            directory: project.directory,
+            portRange: project.portRange ?? null,
+            portRangeCode: project.portRangeCode ?? null,
+            companion: project.description.companion,
+            locations: project.description.locations,
+            workspaces: project.workspaces,
+        })),
+        issues: inventory.issues.map(({ path, message }) => ({ path, message })),
+    };
+    return renderJson(report);
+}
+export function renderProjectDoctor(inventory) {
+    if (inventory.issues.length === 0) {
+        return (`[ok] Project inventory: ${renderCount(inventory.projects.length, "project")}, ` +
+            `${renderCount(inventory.directories.length, "directory")}\n`);
+    }
+    return `${inventory.issues.map(renderInventoryIssue).join("\n")}\n`;
+}
+function renderCount(value, singular) {
+    return `${value} ${singular}${value === 1 ? "" : "s"}`;
+}
+function renderInventoryIssue(issue) {
+    if (issue.conflict !== undefined) {
+        const { left, right } = issue.conflict;
+        return (`[error] Port conflict: ${renderOutputValue(left.path)} (${renderRange(left.portRange)}) ` +
+            `overlaps ${renderOutputValue(right.path)} (${renderRange(right.portRange)})`);
+    }
+    return (`[error] Project inventory: ${renderOutputValue(issue.path)}: ` +
+        escapeControlCharacters(issue.message));
+}
+export function renderProjectDoctorFailure(message) {
+    return `[error] Project inventory: ${escapeControlCharacters(message)}\n`;
+}
+export function renderProjectStatus(details) {
+    const lines = [
+        "Project:",
+        `  Name: ${renderOutputValue(details.name)}`,
+        `  Path: ${renderOutputValue(details.path)}`,
+        `  Directory: ${renderOutputValue(details.directory)}`,
+        `  Remote host: ${renderNullableValue(details.remoteHost)}`,
+        `  Port range: ${renderProjectRange(details.portRange ?? undefined, details.portRangeCode ?? undefined)}`,
+        `  Config source: ${details.configSource ?? "(none)"}`,
+        `  Companion: ${renderCompanion(details.companion)}`,
+        `  DEVELOPERS.md: ${renderLocation(details.locations["DEVELOPERS.md"])}`,
+        `  Work files: ${renderLocation(details.locations[".plans"])}`,
+        `  Work-files folder: ${renderNullableValue(details.plansFolder)}`,
+        `  Ticket id pattern: ${renderNullableValue(details.ticketIdPattern)}`,
+        `  Workspaces: ${renderValues(details.workspaces)}`,
+        "  Worktrees:",
+    ];
+    if (details.worktrees.length === 0)
+        lines.push("    (none)");
+    for (const worktree of details.worktrees) {
+        lines.push(`  - Name: ${renderOutputValue(worktree.name)}`, `    Path: ${renderOutputValue(worktree.path)}`, `    Branch: ${worktree.branch === null ? "(detached)" : renderOutputValue(worktree.branch)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderCompanion(companion) {
+    if (companion === null)
+        return "(none)";
+    return renderPath(companion.dir, companion.exists);
+}
+function renderLocation(location) {
+    return renderPath(location.path, location.exists);
+}
+function renderPath(path, exists) {
+    return `${renderOutputValue(path)}${exists ? "" : " (missing)"}`;
+}
+export function renderProjectStatusJson(details) {
+    return renderJson(details);
+}
+export function renderPortRangeJson(range) {
+    return renderJson(range);
+}
+function renderJson(value) {
+    return `${escapeAdditionalJsonCharacters(JSON.stringify(value, undefined, 2))}\n`;
+}
+function renderRange(range) {
+    return range === undefined ? "(none)" : formatRange(range);
+}
+function renderProjectRange(range, code) {
+    if (range === undefined)
+        return "(none)";
+    return `${formatRange(range)}${code === undefined ? "" : ` (${code})`}`;
+}
+function renderMarkerRange(range) {
+    const code = range.code ?? "default";
+    const description = range.description === undefined ? "" : ` — ${escapeControlCharacters(range.description)}`;
+    return `${formatRange(range)} (${code})${description}`;
+}
+function renderValues(values) {
+    return values.length === 0 ? "(none)" : values.map(renderOutputValue).join(", ");
+}
+function renderNullableValue(value) {
+    return value === null ? "(none)" : renderOutputValue(value);
+}
+function renderOutputValue(value) {
+    return escapeAdditionalJsonCharacters(JSON.stringify(value));
+}

package/dist/project/status.d.ts

@@ -0,0 +1,24 @@
+import type { ProjectInventory } from "./discovery.js";
+import type { CompanionReport, ConfigSource, ItemLocation, ItemName } from "./layout.js";
+import type { PortRange } from "./markers.js";
+export interface ProjectDetails {
+    name: string;
+    path: string;
+    directory: string;
+    remoteHost: string | null;
+    portRange: PortRange | null;
+    portRangeCode: string | null;
+    plansFolder: string | null;
+    ticketIdPattern: string | null;
+    configSource: ConfigSource | null;
+    companion: CompanionReport | null;
+    locations: Record<ItemName, ItemLocation>;
+    workspaces: string[];
+    worktrees: ProjectWorktree[];
+}
+export interface ProjectWorktree {
+    branch: string | null;
+    name: string;
+    path: string;
+}
+export declare function getProjectStatus(inventory: ProjectInventory, inputPath: string): ProjectDetails;

package/dist/project/status.js

@@ -0,0 +1,110 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, isAbsolute, resolve } from "node:path";
+import { errorMessage, isNodeError } from "../errors.js";
+const URL_WITH_AUTHORITY = /^[A-Za-z][A-Za-z\d+.-]*:\/\//u;
+export function getProjectStatus(inventory, inputPath) {
+    const path = resolveProjectPath(inventory.root, inputPath);
+    const project = inventory.projects.find((candidate) => candidate.path === path);
+    if (project === undefined) {
+        throw new Error(`${path} is not a project of ${inventory.root}. Pass the main-worktree path of a git ` +
+            "repository in that projects directory.");
+    }
+    return buildProjectDetails(project);
+}
+function resolveProjectPath(root, inputPath) {
+    const path = isAbsolute(inputPath) ? inputPath : resolve(root, inputPath);
+    try {
+        return realpathSync(path);
+    }
+    catch (error) {
+        if (isNodeError(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+            return path;
+        throw error;
+    }
+}
+function buildProjectDetails(project) {
+    return {
+        name: project.name,
+        path: project.path,
+        directory: project.directory,
+        remoteHost: readRemoteHost(project.path),
+        portRange: project.portRange ?? null,
+        portRangeCode: project.portRangeCode ?? null,
+        plansFolder: project.description.config?.plans?.folder ?? null,
+        ticketIdPattern: project.description.config?.ticketIdPattern ?? null,
+        configSource: project.description.source,
+        companion: project.description.companion,
+        locations: project.description.locations,
+        workspaces: project.workspaces,
+        worktrees: readWorktrees(project.path),
+    };
+}
+function readRemoteHost(projectPath) {
+    const remotes = runGit(projectPath, "remote")
+        .trimEnd()
+        .split("\n")
+        .filter((remote) => remote.length > 0)
+        .toSorted();
+    const orderedRemotes = remotes.includes("origin")
+        ? ["origin", ...remotes.filter((remote) => remote !== "origin")]
+        : remotes;
+    for (const remote of orderedRemotes) {
+        const host = remoteHost(runGit(projectPath, "remote", "get-url", "--", remote).trim());
+        if (host !== null)
+            return host;
+    }
+    return null;
+}
+function remoteHost(remoteUrl) {
+    return URL_WITH_AUTHORITY.test(remoteUrl) ? urlRemoteHost(remoteUrl) : scpRemoteHost(remoteUrl);
+}
+function urlRemoteHost(remoteUrl) {
+    try {
+        const host = new URL(remoteUrl).hostname;
+        return host.length === 0 ? null : host;
+    }
+    catch {
+        return null;
+    }
+}
+function scpRemoteHost(remoteUrl) {
+    if (/^[A-Za-z]:[\\/]/u.test(remoteUrl))
+        return null;
+    const match = /^(?:[^@/:\s]+@)?(\[[^\]]+\]|[^/:\s]+):/u.exec(remoteUrl);
+    return match?.[1] ?? null;
+}
+function readWorktrees(projectPath) {
+    return runGit(projectPath, "worktree", "list", "--porcelain", "-z")
+        .split("\0\0")
+        .filter((record) => record.length > 0)
+        .map(parseWorktree);
+}
+function parseWorktree(record) {
+    const fields = record.split("\0");
+    const pathField = fields.find((field) => field.startsWith("worktree "));
+    if (pathField === undefined)
+        throw new Error("Git returned a worktree record without a path");
+    const path = realpathSync(pathField.slice("worktree ".length));
+    const branchField = fields.find((field) => field.startsWith("branch "));
+    return {
+        branch: branchField === undefined ? null : shortBranch(branchField.slice("branch ".length)),
+        name: basename(path),
+        path,
+    };
+}
+function shortBranch(branch) {
+    const prefix = "refs/heads/";
+    return branch.startsWith(prefix) ? branch.slice(prefix.length) : branch;
+}
+function runGit(projectPath, ...args) {
+    try {
+        return execFileSync("git", ["-C", projectPath, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        throw new Error(`Cannot inspect Git project ${projectPath}: ${errorMessage(error)}`);
+    }
+}

package/dist/templates.d.ts

@@ -0,0 +1 @@
+export declare function readTemplate(relativePath: string): string;

package/dist/templates.js

@@ -0,0 +1,5 @@
+import { readFileSync } from "node:fs";
+// Templates are read at runtime, so edits to a mounted checkout apply without a rebuild.
+export function readTemplate(relativePath) {
+    return readFileSync(new URL(`../templates/${relativePath}`, import.meta.url), "utf-8");
+}

package/package.json

@@ -1,14 +1,49 @@
 {
   "name": "aligndev",
-  "version": "0.0.0",
+  "version": "0.18.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
-  "description": "The AlignFirst Dev Kit CLI. Placeholder release: use a later version.",
+  "description": "The AlignFirst Dev Kit CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
+  "keywords": [
+    "ai",
+    "agent",
+    "alignfirst",
+    "cli",
+    "claude",
+    "codex",
+    "git",
+    "projects",
+    "worktrees"
+  ],
   "homepage": "https://alignfirst.paroi.tech/openclaw-dev-kit",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/paleo/alignfirst.git",
     "directory": "packages/aligndev"
   },
-  "files": ["README.md"]
+  "engines": {
+    "node": ">=24.16.0"
+  },
+  "packageManager": "npm@11.19.0",
+  "type": "module",
+  "bin": {
+    "aligndev": "bin/aligndev.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "arktype": "^2.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "~24.13.3",
+    "rimraf": "~6.1.3",
+    "typescript": "~7.0.2",
+    "vitest": "~5.0.1"
+  }
 }