create-religion 0.4.0 → 1.0.0

package/README.md

@@ -12,7 +12,7 @@ every diff before it lands.
 
 ## What it installs
 
-- **22 skills** your AI tool can run: `feature`, `implement`, `check`, `audit`, `complete`,
+- **25 skills** your AI tool can run: `feature`, `implement`, `check`, `audit`, `complete`,
   and the rest of the loop around them.
 - **A state directory** holding your plans, the active spec, the findings ledger, and the
   archive of everything finished.
@@ -42,8 +42,24 @@ Installing the package globally shortens these to `religion status` and the rest
 `update` will not overwrite a file you have edited. It tells you what conflicts and backs
 up the original if you choose to replace it.
 
+### Exit codes
+
+The same for every command, so a script can rely on them:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | the command did what it was asked |
+| `1` | it ran and reports failure: no project found, a failing `doctor` check, conflicts, declined merges or linked files left by `install` or `update`, a project installed by a newer version, or an unexpected error |
+| `2` | usage error: nothing was written |
+
 ## Documentation
 
+- [Getting started](https://github.com/foo-stack/religion/blob/main/docs/getting-started.md)
+- [What the loop actually feels like](https://github.com/foo-stack/religion/blob/main/docs/the-loop.md)
+- [What to do when doctor complains](https://github.com/foo-stack/religion/blob/main/docs/doctor.md)
+- [Updating a project](https://github.com/foo-stack/religion/blob/main/docs/upgrading.md)
+- [Stability](https://github.com/foo-stack/religion/blob/main/docs/stability.md)
+
 [github.com/foo-stack/religion](https://github.com/foo-stack/religion)
 
 MIT.

package/dist/bin/religion.js

@@ -11,10 +11,11 @@ import fsSync from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "../lib/args.js";
 import { startDashboard } from "../lib/dashboard.js";
-import { renderDoctor, runDoctor } from "../lib/doctor.js";
-import { ADAPTERS, applyInstall, planInstall, readManifest, wireHooks, writeManifest } from "../lib/install.js";
-import { findProjectRoot, STATE_DIR } from "../lib/paths.js";
+import { doctorReport, renderDoctor, runDoctor } from "../lib/doctor.js";
+import { ADAPTERS, applyInstall, BACKUPS, manifestRefusal, planInstall, readManifest, wireHooks, writeManifest } from "../lib/install.js";
+import { findProjectRoot } from "../lib/paths.js";
 import { readProjectState } from "../lib/state.js";
 import { computeStatus, renderStatus } from "../lib/status.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -43,7 +44,14 @@ function findPackageRoot(from) {
 const packageRoot = findPackageRoot(here);
 const templateRoot = path.join(packageRoot, "template");
 async function main(argv) {
-    const options = parse(argv);
+    const parsed = parseArgs(argv, { cwd: process.cwd(), isDirectory });
+    if (!parsed.ok) {
+        console.error(parsed.error);
+        console.error("Run `religion help` for usage.");
+        process.exitCode = 2;
+        return;
+    }
+    const options = parsed.options;
     if (options.command === "help")
         return printHelp();
     if (options.command === "install" || options.command === "update")
@@ -60,9 +68,9 @@ async function main(argv) {
         return;
     }
     if (options.command === "doctor") {
-        const results = await runDoctor(root);
-        console.log(options.json ? JSON.stringify(results, null, 2) : renderDoctor(results));
-        if (results.some((r) => !r.ok))
+        const report = doctorReport(await runDoctor(root));
+        console.log(options.json ? JSON.stringify(report, null, 2) : renderDoctor(report.checks));
+        if (!report.healthy)
             process.exitCode = 1;
         return;
     }
@@ -77,6 +85,13 @@ async function runInstall(options) {
     const target = path.resolve(options.target);
     const updating = options.command === "update";
     const previous = await readManifest(target);
+    const packageVersion = await version();
+    const refusal = manifestRefusal(previous, packageVersion);
+    if (refusal) {
+        console.error(refusal);
+        process.exitCode = 1;
+        return;
+    }
     if (updating && !previous) {
         console.log("No manifest found. Files matching the template will be adopted; others are conflicts.");
     }
@@ -88,20 +103,35 @@ async function runInstall(options) {
         conflict: plan.filter((p) => p.action === "conflict").length,
         kept: plan.filter((p) => p.action === "seed-skip").length,
         merge: plan.filter((p) => p.action === "merge").length,
-        remerge: plan.filter((p) => p.action === "remerge").length
+        remerge: plan.filter((p) => p.action === "remerge").length,
+        rebuild: plan.filter((p) => p.action === "rebuild").length,
+        remove: plan.filter((p) => p.action === "remove").length,
+        release: plan.filter((p) => p.action === "release").length,
+        linked: plan.filter((p) => p.action === "linked").length
     };
     console.log(`\nAdapters: ${adapters.map((a) => ADAPTERS[a].label).join(", ")}`);
     console.log(`  create   ${counts.create}`);
     console.log(`  update   ${counts.update}`);
     console.log(`  keep     ${counts.kept}  (your files, never overwritten)`);
     console.log(`  conflict ${counts.conflict}`);
+    for (const entry of plan.filter((p) => p.action === "conflict"))
+        console.log(`    ${entry.relative}`);
     if (counts.merge > 0)
         console.log(`  merge    ${counts.merge}  (your file, awaiting a decision)`);
     if (counts.remerge > 0)
         console.log(`  merged   ${counts.remerge}  (your sections kept)`);
-    for (const entry of plan.filter((p) => p.action === "conflict")) {
+    if (counts.rebuild > 0)
+        console.log(`  rebuilt  ${counts.rebuild}  (your sections kept, original backed up)`);
+    if (counts.remove > 0)
+        console.log(`  remove   ${counts.remove}  (no longer shipped)`);
+    if (counts.release > 0)
+        console.log(`  release  ${counts.release}  (no longer shipped, but edited by you, so left alone)`);
+    for (const entry of plan.filter((p) => p.action === "release"))
+        console.log(`    ${entry.relative}`);
+    if (counts.linked > 0)
+        console.log(`  linked   ${counts.linked}  (reached through a symbolic link, never written)`);
+    for (const entry of plan.filter((p) => p.action === "linked"))
         console.log(`    ${entry.relative}`);
-    }
     const mergeable = plan.filter((p) => p.action === "merge").map((p) => p.relative);
     let merge = false;
     if (mergeable.length > 0) {
@@ -110,7 +140,7 @@ async function runInstall(options) {
             console.log(`    ${relative}`);
         console.log("\nReligion can append its own sections to them inside markers, keeping everything" +
             "\nyou wrote exactly where it is. Later updates then replace only what is between" +
-            "\nthose markers. The originals are backed up either way.");
+            "\nthose markers. The originals are backed up first.");
         merge = await confirmMerge(options.yes);
     }
     if (options.dryRun) {
@@ -121,14 +151,39 @@ async function runInstall(options) {
         throw new Error(`No template files found under ${templateRoot}. Nothing would be installed, which is never correct.`);
     }
     const result = await applyInstall(templateRoot, target, plan, { force: options.force, merge });
-    await writeManifest(target, await version(), adapters, templateRoot, previous, result.conflicts);
+    await writeManifest(target, packageVersion, adapters, templateRoot, previous, [
+        ...result.conflicts,
+        ...result.declined,
+        ...result.linked
+    ]);
     console.log(`\nWrote ${result.written.length} file(s).`);
     if (result.merged.length > 0) {
         console.log(`Merged ${result.merged.length} entry file(s), keeping what you wrote.`);
     }
-    if (result.backups.length > 0)
-        console.log(`Backed up ${result.backups.length} conflicting file(s).`);
+    if (result.rebuilt.length > 0) {
+        console.log(`Rebuilt ${result.rebuilt.length} entry file(s) around the sections you wrote. The originals are in ` +
+            `${BACKUPS}.`);
+    }
+    if (result.removed.length > 0)
+        console.log(`Removed ${result.removed.length} file(s) this version no longer ships.`);
+    if (result.released.length > 0) {
+        console.log(`Left ${result.released.length} file(s) this version no longer ships, because you edited them. They are yours now.`);
+    }
+    if (result.backups.length > 0) {
+        console.log(`Backed up ${result.backups.length} file(s) to ${BACKUPS} before changing them.`);
+    }
+    if (result.linked.length > 0) {
+        process.exitCode = 1;
+        console.log(`\n${result.linked.length} file(s) are reached through a symbolic link and were left alone, since writing` +
+            `\nthem would write wherever the link points. Replace the links with real files and run again.`);
+    }
+    if (result.declined.length > 0) {
+        process.exitCode = 1;
+        console.log(`\n${result.declined.length} file(s) of yours were not merged, so Religion's instructions are not in them.` +
+            `\nRun update again and accept the merge, or pass --yes, to add them.`);
+    }
     if (result.conflicts.length > 0) {
+        process.exitCode = 1;
         console.log(`\n${result.conflicts.length} file(s) were changed locally and left alone.` +
             `\nReview them, then re-run with --force to replace them (originals are backed up).`);
     }
@@ -137,9 +192,14 @@ async function runInstall(options) {
         if (wired === "written") {
             console.log("Wired the enforcement hooks into .claude/settings.json.");
         }
+        else if (wired === "linked") {
+            process.exitCode = 1;
+            console.log("\n.claude/settings.json is a symbolic link and was left alone." +
+                "\nIf a hook is missing, compare the file it points to with a fresh install's .claude/settings.json.");
+        }
         else if (wired === "exists") {
             console.log("\n.claude/settings.json already exists and was left alone." +
-                `\nTo enable the hooks, merge ${path.join(STATE_DIR, ".state", "settings-template.json")} into it.`);
+                "\nIf a hook is missing, compare it with a fresh install's .claude/settings.json.");
         }
     }
     if (!updating) {
@@ -187,39 +247,13 @@ async function version() {
         return "0.0.0";
     }
 }
-function parse(argv) {
-    const options = {
-        command: "install",
-        adapters: null,
-        json: false,
-        dryRun: false,
-        force: false,
-        yes: false,
-        target: process.cwd()
-    };
-    const commands = new Set(["install", "update", "status", "doctor", "dashboard", "help"]);
-    const adapters = [];
-    for (const arg of argv) {
-        if (commands.has(arg))
-            options.command = arg;
-        else if (arg === "--json")
-            options.json = true;
-        else if (arg === "--dry-run")
-            options.dryRun = true;
-        else if (arg === "--force")
-            options.force = true;
-        else if (arg === "--yes" || arg === "-y")
-            options.yes = true;
-        else if (arg === "--help" || arg === "-h")
-            options.command = "help";
-        else if (arg.startsWith("--") && arg.slice(2) in ADAPTERS)
-            adapters.push(arg.slice(2));
-        else if (!arg.startsWith("-"))
-            options.target = arg;
-    }
-    if (adapters.length > 0)
-        options.adapters = adapters;
-    return options;
+function isDirectory(candidate) {
+    try {
+        return fsSync.statSync(path.resolve(candidate)).isDirectory();
+    }
+    catch {
+        return false;
+    }
 }
 function printHelp() {
     console.log(`religion - a file-backed, spec-driven AI development workflow
@@ -239,6 +273,13 @@ Options
   --force       replace locally-changed managed files, backing them up first
   --json        machine-readable output for status and doctor
   --yes         no prompts
+
+Exit codes
+  0   the command did what it was asked
+  1   it ran and reports failure: no project found, a failing doctor check,
+      conflicts, declined merges or linked files left by install or update,
+      a project installed by a newer version, or an unexpected error
+  2   usage error: nothing was written
 `);
 }
 main(process.argv.slice(2)).catch((error) => {

package/dist/lib/args.js

@@ -0,0 +1,108 @@
+/**
+ * The command-line grammar.
+ *
+ * Pure, so every rule is testable: the working directory and the one filesystem question it
+ * needs, whether a bare word names an existing directory, are passed in. Anything it does
+ * not understand is refused rather than guessed at, because a guess here is an install into
+ * the wrong place.
+ */
+import { ADAPTERS } from "./install.js";
+const COMMANDS = ["install", "update", "status", "doctor", "dashboard", "help"];
+const WRITES = new Set(["install", "update"]);
+const REPORTS = new Set(["status", "doctor"]);
+const EVERY = new Set(COMMANDS);
+/** Every option, the commands it applies to, and what it does. Parsing dispatches on this alone. */
+const FLAGS = {
+    "--help": { commands: EVERY, apply: (options) => void (options.command = "help") },
+    "-h": { commands: EVERY, apply: (options) => void (options.command = "help") },
+    "--dry-run": { commands: WRITES, apply: (options) => void (options.dryRun = true) },
+    "--force": { commands: WRITES, apply: (options) => void (options.force = true) },
+    "--yes": { commands: WRITES, apply: (options) => void (options.yes = true) },
+    "-y": { commands: WRITES, apply: (options) => void (options.yes = true) },
+    "--json": { commands: REPORTS, apply: (options) => void (options.json = true) },
+    ...Object.fromEntries(Object.keys(ADAPTERS).map((adapter) => [
+        `--${adapter}`,
+        {
+            commands: WRITES,
+            apply: (options) => {
+                const chosen = options.adapters ?? [];
+                if (!chosen.includes(adapter))
+                    options.adapters = [...chosen, adapter];
+            }
+        }
+    ]))
+};
+/** The options each command accepts, read from the same table parsing uses. */
+export const GRAMMAR = grammar();
+function grammar() {
+    const table = {};
+    for (const command of COMMANDS)
+        table[command] = Object.keys(FLAGS).filter((flag) => FLAGS[flag].commands.has(command));
+    return table;
+}
+export function parseArgs(argv, context) {
+    const options = {
+        command: "install",
+        adapters: null,
+        json: false,
+        dryRun: false,
+        force: false,
+        yes: false,
+        target: context.cwd
+    };
+    if (argv.some((arg) => arg === "help" || arg === "--help" || arg === "-h")) {
+        return { ok: true, options: { ...options, command: "help" } };
+    }
+    const [first, ...rest] = argv.filter((arg) => !arg.startsWith("-"));
+    let extra = [];
+    if (first !== undefined && isCommand(first)) {
+        options.command = first;
+        if (rest[0] !== undefined)
+            options.target = rest[0];
+        extra = rest.slice(1);
+    }
+    else if (first !== undefined) {
+        if (!context.isDirectory(first))
+            return fail(unknownCommand(first));
+        options.target = first;
+        extra = rest;
+    }
+    if (extra.length > 0) {
+        return fail(`Unexpected argument '${extra[0]}'. ${options.command} takes at most one directory.`);
+    }
+    for (const flag of argv.filter((arg) => arg.startsWith("-"))) {
+        const known = Object.hasOwn(FLAGS, flag) ? FLAGS[flag] : undefined;
+        if (!known)
+            return fail(`Unknown option '${flag}'.`);
+        if (!known.commands.has(options.command))
+            return fail(`Option '${flag}' does not apply to ${options.command}.`);
+        known.apply(options);
+    }
+    return { ok: true, options };
+}
+function isCommand(word) {
+    return COMMANDS.includes(word);
+}
+function fail(error) {
+    return { ok: false, error };
+}
+function unknownCommand(word) {
+    const closest = COMMANDS.map((command) => ({ command, distance: editDistance(word, command) }))
+        .filter((candidate) => candidate.distance <= 2)
+        .sort((a, b) => a.distance - b.distance)[0];
+    return closest
+        ? `Unknown command '${word}'. Did you mean '${closest.command}'?`
+        : `Unknown command '${word}', and no directory of that name exists.`;
+}
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current.push(Math.min(previous[j] + 1, current[j - 1] + 1, substitution));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}

package/dist/lib/dashboard.js

@@ -10,27 +10,50 @@ import { readIfPresent, statePath } from "./paths.js";
 import { readProjectState } from "./state.js";
 import { computeStatus } from "./status.js";
 export async function startDashboard(root) {
+    let port = 0;
     const server = http.createServer((request, response) => {
-        void handle(root, request, response);
+        void handle(root, port, request, response);
     });
     await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
     const address = server.address();
-    const port = typeof address === "object" && address ? address.port : 0;
+    port = typeof address === "object" && address ? address.port : 0;
     return {
         url: `http://127.0.0.1:${port}`,
+        address: typeof address === "object" && address ? address.address : "",
         close: () => new Promise((resolve) => server.close(() => resolve()))
     };
 }
-async function handle(root, request, response) {
+/**
+ * Whether a request was addressed to this server by name, not only by socket.
+ *
+ * Binding to loopback keeps other machines out, but not a page elsewhere whose domain has
+ * been rebound to 127.0.0.1: the browser connects here and sends that domain as the Host.
+ * Answering only our own name refuses it.
+ */
+export function isOwnHost(host, port) {
+    const name = host?.toLowerCase();
+    return name === `127.0.0.1:${port}` || name === `localhost:${port}`;
+}
+/** What every response allows a browser to load: inline script and style, and its own server. */
+export const CONTENT_SECURITY_POLICY = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'";
+async function handle(root, port, request, response) {
+    if (!isOwnHost(request.headers.host, port)) {
+        send(response, 403, "text/plain; charset=utf-8", "Forbidden: this dashboard only answers requests addressed to itself.");
+        return;
+    }
     if (request.url === "/state.json") {
         const state = await readProjectState(root);
         const activity = await readActivity(root);
-        response.writeHead(200, { "content-type": "application/json" });
-        response.end(JSON.stringify({ status: computeStatus(state), plan: state.plan, findings: state.findings, activity }));
+        const body = JSON.stringify({ status: computeStatus(state), plan: state.plan, findings: state.findings, activity });
+        send(response, 200, "application/json", body);
         return;
     }
-    response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-    response.end(PAGE);
+    send(response, 200, "text/html; charset=utf-8", PAGE);
+}
+/** The only way this server answers, so no response can leave out the policy. */
+function send(response, status, type, body) {
+    response.writeHead(status, { "content-type": type, "content-security-policy": CONTENT_SECURITY_POLICY });
+    response.end(body);
 }
 async function readActivity(root) {
     const raw = await readIfPresent(statePath(root, ".state", "run.json"));

package/dist/lib/doctor.js

@@ -26,7 +26,8 @@ const REQUIRED = [
     "history/spikes",
     "reference"
 ];
-const ALLOWED = {
+/** The values each enumerated setting accepts. Other settings are not checked. */
+export const ALLOWED = {
     "workflow.stepReview": ["every", "item"],
     "git.mode": ["trunk", "branch-per-item", "pull-request"],
     "git.checkpoints": ["none", "every-step", "squash"],
@@ -147,6 +148,9 @@ function invalidSettings(config) {
     }
     return problems;
 }
+export function doctorReport(checks) {
+    return { schemaVersion: 1, healthy: checks.every((check) => check.ok), checks: [...checks] };
+}
 export function renderDoctor(results) {
     const failures = results.filter((r) => !r.ok);
     const order = { work: 0, completion: 1, nothing: 2 };