alignfirst 0.9.0 → 0.10.0

package/README.md

@@ -141,7 +141,7 @@ The companion directory is `~/.alignfirst/companions/<name>`. The name is the ma
 An agent reads a repository's `AGENTS.md` on its own, but never a companion. When your repositories carry no AlignFirst instructions, add this line to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
 
 ```text
-In a git repository, run `alignfirst context` as your first command, whatever the task, unless the project's instructions already say so.
+In a git repository, run `npx -y alignfirst context` as your first command, whatever the task, unless the project's instructions already say so.
 ```
 
 ## Upgrade from v1, v2, or v3

package/dist/commands/doctor.js

@@ -1,7 +1,6 @@
 import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import semver from "semver";
 import { resolveDefaultBranch } from "../default-branch.js";
 import { errorMessage } from "../errors.js";
 import { parseBareCommandArgs } from "../parse-args.js";
@@ -11,6 +10,7 @@ import { PROJECT_CONFIG_FILENAME, resolveProjectConfig, } from "../project-confi
 import { registryPath, sharedCompanionDirs, strayRegistryKeys, ITEM_NAMES, layoutOf, renderItemLocation, } from "../project-layout.js";
 import { COMMAND_SKILLS, findInstalledSkill } from "../skills.js";
 import { cliRangeResult } from "../version-guard.js";
+import { isAheadOfRange } from "../version-range.js";
 export function runDoctor(ctx, args) {
     const usage = `Usage: ${ctx.form} doctor\n`;
     if (parseBareCommandArgs(ctx, args, usage))
@@ -62,7 +62,7 @@ function inspectConfig(ctx, resolved) {
         level: result.satisfied ? "ok" : "error",
         text: `${result.satisfied ? "satisfies" : "does not satisfy"} ${result.range}`,
     });
-    if (semver.gtr(ctx.version, result.range))
+    if (isAheadOfRange(ctx.version, result.range))
         lines.push({ level: "warn", text: `${ctx.version} is ahead of ${result.range}` });
     return lines;
 }
@@ -154,11 +154,17 @@ function describeCommandSkill({ name, installed }) {
 }
 function describeInstalledSkill(name, installed) {
     const version = installed.version ?? "unknown";
-    const parsed = semver.parse(installed.version);
-    if (parsed === null || parsed.major < 4)
+    const major = majorOf(installed.version);
+    if (major === undefined || major < 4)
         return {
             level: "warn",
             text: `${name} ${version} predates v4; update: npx -y skills update --global --yes`,
         };
     return { level: "ok", text: `${name} ${version} (${installed.root})` };
 }
+function majorOf(version) {
+    if (version === undefined)
+        return;
+    const match = /^(\d+)\./.exec(version);
+    return match === null ? undefined : Number(match[1]);
+}

package/dist/json-shape.d.ts

@@ -0,0 +1,19 @@
+export type Check<T> = (value: unknown, path: string) => T;
+export interface OptionalField<T> {
+    optional: Check<T>;
+}
+type Fields<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? OptionalField<Exclude<T[K], undefined>> : Check<T[K]>;
+};
+/** Runs `check` at the root; a shape failure becomes `toError(<message>)`. */
+export declare function parseShape<T>(check: Check<T>, value: unknown, toError: (detail: string) => Error): T;
+/** Rejects the first unknown key, then checks each field in declaration order. */
+export declare function object<T extends object>(fields: Fields<T>): Check<T>;
+export declare function shapeError(path: string, expectation: string): Error;
+export declare function optional<T>(check: Check<T>): OptionalField<T>;
+export declare function record<T>(check: Check<T>): Check<Record<string, T>>;
+export declare function literal<const T extends readonly (string | number)[]>(...values: T): Check<T[number]>;
+export declare function integerBetween(min: number, max: number): Check<number>;
+export declare function nonEmptyString(value: unknown, path: string): string;
+export declare function boolean(value: unknown, path: string): boolean;
+export {};

package/dist/json-shape.js

@@ -0,0 +1,93 @@
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+class ShapeError extends Error {
+}
+/** Runs `check` at the root; a shape failure becomes `toError(<message>)`. */
+export function parseShape(check, value, toError) {
+    try {
+        return check(value, "");
+    }
+    catch (error) {
+        if (error instanceof ShapeError)
+            throw toError(error.message);
+        throw error;
+    }
+}
+/** Rejects the first unknown key, then checks each field in declaration order. */
+export function object(fields) {
+    const entries = Object.entries(fields);
+    return (value, path) => {
+        if (!isPlainObject(value))
+            throw shapeError(path, "be an object");
+        const unknownKey = Object.keys(value).find((key) => !Object.hasOwn(fields, key));
+        if (unknownKey !== undefined)
+            throw shapeError(childPath(path, unknownKey), "be removed");
+        const result = {};
+        for (const [key, field] of entries) {
+            const fieldPath = childPath(path, key);
+            if (typeof field === "function")
+                result[key] = field(value[key], fieldPath);
+            else if (value[key] !== undefined)
+                result[key] = field.optional(value[key], fieldPath);
+        }
+        // The fields mirror T key by key.
+        return result;
+    };
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function childPath(path, key) {
+    if (!IDENTIFIER.test(key))
+        return bracketPath(path, JSON.stringify(key));
+    return path === "" ? key : `${path}.${key}`;
+}
+function bracketPath(path, segment) {
+    return `${path === "" ? "value" : path}[${segment}]`;
+}
+export function shapeError(path, expectation) {
+    return new ShapeError(`${path === "" ? "value" : path} must ${expectation}`);
+}
+export function optional(check) {
+    return { optional: check };
+}
+export function record(check) {
+    return (value, path) => {
+        if (!isPlainObject(value))
+            throw shapeError(path, "be an object");
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, check(item, childPath(path, key))]));
+    };
+}
+export function literal(...values) {
+    const expectation = `be ${listOf(values.map((item) => JSON.stringify(item)))}`;
+    return (value, path) => {
+        const match = values.find((item) => item === value);
+        if (match === undefined)
+            throw shapeError(path, expectation);
+        return match;
+    };
+}
+function listOf(items) {
+    if (items.length === 1)
+        return items[0];
+    return `${items.slice(0, -1).join(", ")} or ${items.at(-1)}`;
+}
+export function integerBetween(min, max) {
+    return (value, path) => {
+        if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max)
+            throw shapeError(path, `be an integer from ${min} to ${max}`);
+        return value;
+    };
+}
+export function nonEmptyString(value, path) {
+    if (typeof value !== "string" || value.length === 0)
+        throw shapeError(path, "be a non-empty string");
+    return value;
+}
+export function boolean(value, path) {
+    if (typeof value !== "boolean")
+        throw shapeError(path, "be a boolean");
+    return value;
+}

package/dist/project-config.js

@@ -1,39 +1,34 @@
 import { readFileSync } from "node:fs";
-import { type } from "arktype";
-import semver from "semver";
 import { CliError } from "./cli-error.js";
 import { errorMessage } from "./errors.js";
+import { boolean, integerBetween, literal, nonEmptyString, object, optional, parseShape, } from "./json-shape.js";
+import { isValidVersionRange } from "./version-range.js";
 export const PROJECT_CONFIG_FILENAME = ".alignfirst.json";
-const portRangeSchema = type({
-    "+": "reject",
-    first: "1 <= number.integer <= 65535",
-    last: "1 <= number.integer <= 65535",
+const portRangeShape = object({
+    first: integerBetween(1, 65_535),
+    last: integerBetween(1, 65_535),
 });
-const plansSchema = type({
-    "+": "reject",
-    "folder?": "string > 0",
-    "autoArchive?": "boolean",
+const plansShape = object({
+    folder: optional(nonEmptyString),
+    autoArchive: optional(boolean),
 });
-const commitSchema = type({
-    "+": "reject",
-    style: "'conventionalCommit'",
-    "ticketReference?": "'bracketed' | 'bracketedHash'",
+const commitShape = object({
+    style: literal("conventionalCommit"),
+    ticketReference: optional(literal("bracketed", "bracketedHash")),
 });
-const gitSchema = type({
-    "+": "reject",
-    "defaultBranch?": "string > 0",
-    "branchNameTemplate?": "string > 0",
-    "commit?": commitSchema,
-    "agentCoauthoring?": "boolean",
+const gitShape = object({
+    defaultBranch: optional(nonEmptyString),
+    branchNameTemplate: optional(nonEmptyString),
+    commit: optional(commitShape),
+    agentCoauthoring: optional(boolean),
 });
-const projectConfigSchema = type({
-    "+": "reject",
-    schemaVersion: "1",
-    "cli?": "string > 0",
-    "ticketIdPattern?": "string > 0",
-    "plans?": plansSchema,
-    "portRange?": portRangeSchema,
-    "git?": gitSchema,
+const projectConfigShape = object({
+    schemaVersion: literal(1),
+    cli: optional(nonEmptyString),
+    ticketIdPattern: optional(nonEmptyString),
+    plans: optional(plansShape),
+    portRange: optional(portRangeShape),
+    git: optional(gitShape),
 });
 export function resolveProjectConfig(layout) {
     const location = layout.locations[PROJECT_CONFIG_FILENAME];
@@ -52,11 +47,9 @@ export function readProjectConfig(path) {
     return validateProjectConfig(value, path);
 }
 export function validateProjectConfig(value, label) {
-    const config = projectConfigSchema(value);
-    if (config instanceof type.errors)
-        throw invalidConfig(label, config.summary.split("\n", 1)[0]);
-    if (config.cli !== undefined && semver.validRange(config.cli) === null)
-        throw invalidConfig(label, `cli is not a valid semver range: ${config.cli}`);
+    const config = parseShape(projectConfigShape, value, (detail) => invalidConfig(label, detail));
+    if (config.cli !== undefined && !isValidVersionRange(config.cli))
+        throw invalidConfig(label, `cli is not a supported version range: ${config.cli}`);
     if (config.ticketIdPattern !== undefined)
         assertValidPattern(config.ticketIdPattern, label);
     if (config.portRange !== undefined)

package/dist/project-layout.js

@@ -1,9 +1,9 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { type } from "arktype";
 import { CliError } from "./cli-error.js";
 import { errorMessage } from "./errors.js";
 import { gitOutputOrUndefined } from "./git.js";
+import { object, optional, parseShape, record, shapeError } from "./json-shape.js";
 export const ITEM_NAMES = [
     ".alignfirst.json",
     ".alignfirst-instructions",
@@ -15,20 +15,15 @@ export const ITEM_NAMES = [
 // The directory holding the companions and their registry. A symlink there moves them elsewhere.
 const COMPANIONS_ROOT = "~/.alignfirst/companions";
 const REGISTRY_FILE = "registry.json";
-const FLAG = "boolean | 'auto'";
-const flagsSchema = type({
-    "+": "reject",
-    ".alignfirst.json?": FLAG,
-    ".alignfirst-instructions?": FLAG,
-    "DEVELOPERS.md?": FLAG,
-    "docs?": FLAG,
-    ".plans?": FLAG,
-    "_aligndev?": FLAG,
-});
-const registrySchema = type({
-    "+": "reject",
-    paths: type.Record("string", flagsSchema),
+const flagsShape = object({
+    ".alignfirst.json": optional(flag),
+    ".alignfirst-instructions": optional(flag),
+    "DEVELOPERS.md": optional(flag),
+    docs: optional(flag),
+    ".plans": optional(flag),
+    _aligndev: optional(flag),
 });
+const registryFileShape = object({ paths: record(flagsShape) });
 export function layoutOf(ctx) {
     ctx.layout ??= resolveProjectLayout(ctx.cwd, ctx.home);
     return ctx.layout;
@@ -64,9 +59,7 @@ function readRegistry(home) {
     catch (error) {
         throw invalidRegistry(path, errorMessage(error));
     }
-    const file = registrySchema(value);
-    if (file instanceof type.errors)
-        throw invalidRegistry(path, file.summary.split("\n", 1)[0]);
+    const file = parseShape(registryFileShape, value, (detail) => invalidRegistry(path, detail));
     const badKey = Object.keys(file.paths).find((key) => !isUserPath(key));
     if (badKey !== undefined)
         throw invalidRegistry(path, `paths key must be an absolute path or start with ~/: ${badKey}`);
@@ -78,6 +71,11 @@ export function registryPath(home) {
 function invalidRegistry(path, detail) {
     return new CliError(`Invalid ${path}: ${detail}`);
 }
+function flag(value, path) {
+    if (typeof value !== "boolean" && value !== "auto")
+        throw shapeError(path, 'be a boolean or "auto"');
+    return value;
+}
 function isUserPath(value) {
     return value === "~" || value.startsWith("~/") || isAbsolute(value);
 }

package/dist/version-guard.js

@@ -1,5 +1,5 @@
-import semver from "semver";
 import { CliError } from "./cli-error.js";
+import { satisfiesRange } from "./version-range.js";
 export function checkCliRange(config, installedVersion, commandArgs) {
     const result = cliRangeResult(config, installedVersion);
     if (result === undefined || result.satisfied)
@@ -13,5 +13,5 @@ export function cliRangeResult(config, installedVersion) {
     const range = config?.cli;
     if (range === undefined)
         return;
-    return { range, satisfied: semver.satisfies(installedVersion, range) };
+    return { range, satisfied: satisfiesRange(installedVersion, range) };
 }

package/dist/version-range.d.ts

@@ -0,0 +1,5 @@
+export declare function isValidVersionRange(range: string): boolean;
+/** False for a version with a prerelease tag or an invalid range. */
+export declare function satisfiesRange(version: string, range: string): boolean;
+/** True when `version` is above every version the range accepts. */
+export declare function isAheadOfRange(version: string, range: string): boolean;

package/dist/version-range.js

@@ -0,0 +1,103 @@
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+// Two-character operators first, so `<=` is not read as `<`.
+const OPERATORS = ["<=", ">=", "<", ">", "=", "~", "^"];
+export function isValidVersionRange(range) {
+    return parseRange(range) !== undefined;
+}
+/** False for a version with a prerelease tag or an invalid range. */
+export function satisfiesRange(version, range) {
+    const parsed = parseVersion(version);
+    const sets = parseRange(range);
+    if (parsed === undefined || sets === undefined)
+        return false;
+    return sets.some((set) => set.every((comparator) => holds(comparator, parsed)));
+}
+/** True when `version` is above every version the range accepts. */
+export function isAheadOfRange(version, range) {
+    const parsed = parseVersion(version);
+    const sets = parseRange(range);
+    if (parsed === undefined || sets === undefined)
+        return false;
+    return sets.every((set) => set.some((comparator) => exceeds(comparator, parsed)));
+}
+function parseVersion(text) {
+    const match = VERSION.exec(text);
+    if (match === null)
+        return;
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+function parseRange(range) {
+    const sets = [];
+    for (const part of range.split("||")) {
+        const set = parseComparatorSet(part.trim());
+        if (set === undefined)
+            return;
+        sets.push(set);
+    }
+    return sets;
+}
+function parseComparatorSet(text) {
+    if (text === "")
+        return;
+    const comparators = [];
+    for (const token of text.split(/\s+/)) {
+        const desugared = parseComparator(token);
+        if (desugared === undefined)
+            return;
+        comparators.push(...desugared);
+    }
+    return comparators;
+}
+function parseComparator(token) {
+    const operator = OPERATORS.find((candidate) => token.startsWith(candidate));
+    const version = parseVersion(operator === undefined ? token : token.slice(operator.length));
+    if (version === undefined)
+        return;
+    return desugar(operator ?? "=", version);
+}
+function desugar(operator, version) {
+    if (operator === "~") {
+        const upper = { major: version.major, minor: version.minor + 1, patch: 0 };
+        return [lowerBound(version), { operator: "<", version: upper }];
+    }
+    if (operator === "^")
+        return [lowerBound(version), { operator: "<", version: caretUpper(version) }];
+    return [{ operator, version }];
+}
+function lowerBound(version) {
+    return { operator: ">=", version };
+}
+function caretUpper({ major, minor, patch }) {
+    if (major > 0)
+        return { major: major + 1, minor: 0, patch: 0 };
+    if (minor > 0)
+        return { major: 0, minor: minor + 1, patch: 0 };
+    return { major: 0, minor: 0, patch: patch + 1 };
+}
+function holds({ operator, version }, candidate) {
+    const order = compareVersions(candidate, version);
+    switch (operator) {
+        case "<":
+            return order < 0;
+        case "<=":
+            return order <= 0;
+        case ">":
+            return order > 0;
+        case ">=":
+            return order >= 0;
+        case "=":
+            return order === 0;
+    }
+}
+function compareVersions(left, right) {
+    return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+}
+/** A set is exceeded when the candidate fails one of its upper bounds on the high side. */
+function exceeds({ operator, version }, candidate) {
+    const order = compareVersions(candidate, version);
+    if (operator === "<")
+        return order >= 0;
+    if (operator === "<=" || operator === "=")
+        return order > 0;
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, work files and docs in one command.",
@@ -35,13 +35,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@alignfirst/docmap": "~0.11.1",
-    "arktype": "^2.2.3",
-    "semver": "^7.8.5"
+    "@alignfirst/docmap": "~0.11.1"
   },
   "devDependencies": {
     "@types/node": "~24.13.3",
-    "@types/semver": "~7.8.0",
     "rimraf": "~6.1.3",
     "typescript": "~7.0.2",
     "vitest": "~5.0.1"