@fluado/enmetu 0.0.0-stage → 0.2.0

package/dist/cli/commands/hookCommand.js

@@ -0,0 +1,92 @@
+import { join } from 'node:path';
+import { ConfigError, PreflightError } from '../../contracts/errors.js';
+import { EXIT } from '../../contracts/exitCode.js';
+import { CONFIG_FILE_NAME, DEFAULT_CONFIG, parseConfig, } from '../../core/config/parseConfig.js';
+import { preCommitCheckController } from '../../hooks/preCommitCheckController.js';
+const HOOK_CYCLE_ID = 'hook';
+/**
+ * Controller:
+ * 1. locator.locate(startDir); anything but found: notice, exit 0 (the hook fails open).
+ * 2. parseConfig of <root>/enmetu.config.json; a ConfigError prints a notice and
+ *    applies the defaults, so a broken config never blocks the commit that fixes it.
+ *    Unknown keys are ignored without a word: the daemon names them at start (design 14.17).
+ * 3. preCommitCheckController with the config's skipJsonCheck.
+ * 4. Violations: print the refusal of design 1.18 to stderr, exit 1. None: print nothing, exit 0.
+ */
+export async function hookCommand(input, deps) {
+    // --- Step 1: the repository; a hook is a net, so anything odd lets the commit through ---
+    const location = await locateOrReason(input.startDir, deps);
+    if (location.kind !== 'found') {
+        deps.stderr.write(`enmetu: pre-commit check skipped (${location.reason})\n`);
+        return { exitCode: EXIT.OK };
+    }
+    const { paths } = location;
+    // --- Step 2: the config at the root; defaults when it is broken ---
+    const config = await configForCheck(paths.root, deps);
+    // --- Step 3: the shared content rules over the staged blobs (D11) ---
+    const { violations } = await preCommitCheckController({ cycleId: HOOK_CYCLE_ID }, { git: deps.openGit(paths), skipJsonCheck: config.skipJsonCheck });
+    // --- Step 4: the refusal, or silence ---
+    if (violations.length === 0) {
+        return { exitCode: EXIT.OK };
+    }
+    deps.stderr.write(refusalText(violations));
+    // Git only tells zero from non-zero for hooks (Decision 34).
+    return { exitCode: EXIT.FAILURE };
+}
+async function locateOrReason(startDir, deps) {
+    let location;
+    try {
+        location = await deps.locator.locate(startDir);
+    }
+    catch (error) {
+        if (error instanceof PreflightError) {
+            return { kind: 'skipped', reason: error.message };
+        }
+        throw error;
+    }
+    switch (location.kind) {
+        case 'found':
+            return location;
+        case 'bare':
+            return { kind: 'skipped', reason: `${startDir} is a bare repository` };
+        case 'not-a-repository':
+            return {
+                kind: 'skipped',
+                reason: `${startDir} is not inside a git work tree`,
+            };
+    }
+}
+async function configForCheck(root, deps) {
+    try {
+        return parseConfig(await deps.fs.readText(join(root, CONFIG_FILE_NAME)))
+            .config;
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError)) {
+            throw error;
+        }
+        deps.stderr.write(`enmetu: ignoring ${CONFIG_FILE_NAME} (${error.code}: ${error.message}); using the defaults for this check\n`);
+        return DEFAULT_CONFIG;
+    }
+}
+function refusalText(violations) {
+    const count = violations.length;
+    const files = count === 1
+        ? '1 staged file is not fit to commit'
+        : `${count} staged files are not fit to commit`;
+    return [
+        `enmetu: commit refused, ${files}:`,
+        ...violations.map((violation) => `  ${describeViolation(violation)}`),
+        'Resolve the conflict or fix the file, then stage it again.',
+        'To commit anyway: git commit --no-verify',
+        '',
+    ].join('\n');
+}
+function describeViolation(violation) {
+    switch (violation.rule) {
+        case 'CONFLICT_MARKERS':
+            return `${violation.path}: conflict markers`;
+        case 'INVALID_JSON':
+            return `${violation.path}: is not valid JSON (${violation.detail})`;
+    }
+}

package/dist/cli/commands/resumeCommand.d.ts

@@ -0,0 +1,48 @@
+import { type ExitCode } from '../../contracts/exitCode.js';
+import type { IGitReader } from '../../contracts/IGitReader.js';
+import type { IGitWriter } from '../../contracts/IGitWriter.js';
+import type { IHaltStore } from '../../contracts/IHaltStore.js';
+import type { IInstanceLock } from '../../contracts/IInstanceLock.js';
+import type { IRepositoryLocator, RepositoryPaths } from '../../contracts/IRepositoryLocator.js';
+import type { ITextSink } from '../../contracts/ITextSink.js';
+export interface ResumeSources {
+    readonly lock: IInstanceLock;
+    readonly halt: IHaltStore;
+    readonly git: IGitReader;
+    /** Unguarded: resume owns the halt and moves the verified ref before clearing it. */
+    readonly writer: IGitWriter;
+}
+export interface ResumeCommandInput {
+    readonly startDir: string;
+    /** Adopt the rewritten upstream: move the verified ref to the remote head. */
+    readonly acceptUpstream: boolean;
+}
+export interface ResumeCommandDeps {
+    readonly locator: IRepositoryLocator;
+    readonly openSources: (paths: RepositoryPaths) => ResumeSources;
+    readonly stdout: ITextSink;
+}
+export type ResumeOutcome = 'cleared' | 'nothing-to-resume' | 'refused-instance-running' | 'refused-operation-in-progress' | 'refused-unmerged' | 'refused-upstream-not-reconciled' | 'refused-history-still-local' | 'refused-upstream-unreachable';
+export interface ResumeCommandResult {
+    readonly exitCode: ExitCode;
+    readonly outcome: ResumeOutcome;
+}
+/**
+ * Controller:
+ * 1. locator.locate(startDir); not found or bare: exit 5.
+ * 2. lock.inspect() live: refused-instance-running, exit 4.
+ * 3. halt.read() null: nothing-to-resume, exit 0.
+ * 4. An operation in progress or unmerged paths: refused, exit 3, marker kept.
+ * 5. UPSTREAM_REWRITTEN only, judged against the remote the way the next cycle
+ *    judges it: remoteHead of the branch's upstream, fetched into the incoming
+ *    ref (no upstream, unreachable, absent or a failed fetch:
+ *    refused-upstream-unreachable, exit 3). Clear when the verified ref is an
+ *    ancestor of the remote sha; otherwise require acceptUpstream, refuse while
+ *    the verified ref is still an ancestor of HEAD (the local branch carries
+ *    the rewritten history), then move the verified ref to the remote sha.
+ *    The tracking ref is never the reference: enmetu does not move it to a
+ *    rewritten upstream, so after enmetu's own halt it still equals the
+ *    verified ref and would pass any ancestry check.
+ * 6. halt.clear(), print what was cleared, exit 0.
+ */
+export declare function resumeCommand(input: ResumeCommandInput, deps: ResumeCommandDeps): Promise<ResumeCommandResult>;

package/dist/cli/commands/resumeCommand.js

@@ -0,0 +1,124 @@
+import { EXIT } from '../../contracts/exitCode.js';
+import { incomingRefFor, verifiedRefFor } from '../../core/git/enmetuRefs.js';
+/**
+ * Controller:
+ * 1. locator.locate(startDir); not found or bare: exit 5.
+ * 2. lock.inspect() live: refused-instance-running, exit 4.
+ * 3. halt.read() null: nothing-to-resume, exit 0.
+ * 4. An operation in progress or unmerged paths: refused, exit 3, marker kept.
+ * 5. UPSTREAM_REWRITTEN only, judged against the remote the way the next cycle
+ *    judges it: remoteHead of the branch's upstream, fetched into the incoming
+ *    ref (no upstream, unreachable, absent or a failed fetch:
+ *    refused-upstream-unreachable, exit 3). Clear when the verified ref is an
+ *    ancestor of the remote sha; otherwise require acceptUpstream, refuse while
+ *    the verified ref is still an ancestor of HEAD (the local branch carries
+ *    the rewritten history), then move the verified ref to the remote sha.
+ *    The tracking ref is never the reference: enmetu does not move it to a
+ *    rewritten upstream, so after enmetu's own halt it still equals the
+ *    verified ref and would pass any ancestry check.
+ * 6. halt.clear(), print what was cleared, exit 0.
+ */
+export async function resumeCommand(input, deps) {
+    // --- Step 1: the repository root through git ---
+    const location = await deps.locator.locate(input.startDir);
+    if (location.kind !== 'found') {
+        const reason = location.kind === 'bare'
+            ? 'is a bare repository'
+            : 'is not inside a git work tree';
+        say(deps, `${input.startDir} ${reason}; there is no halt to resume`);
+        return { exitCode: EXIT.NOT_ELIGIBLE, outcome: 'nothing-to-resume' };
+    }
+    const sources = deps.openSources(location.paths);
+    // --- Step 2: a running daemon owns the repository ---
+    const holder = await sources.lock.inspect();
+    if (holder !== null) {
+        say(deps, `resume refused: enmetu runs on this worktree (pid ${holder.pid} on ${holder.hostname} since ${holder.startedAt}); stop it first`);
+        return { exitCode: EXIT.LOCKED, outcome: 'refused-instance-running' };
+    }
+    // --- Step 3: the halt marker ---
+    const record = await sources.halt.read();
+    if (record === null) {
+        say(deps, 'not halted; nothing to resume');
+        return { exitCode: EXIT.OK, outcome: 'nothing-to-resume' };
+    }
+    // --- Step 4: no operation in progress, nothing unmerged ---
+    const state = await sources.git.repositoryState();
+    if (state.operation !== null) {
+        return refuse(deps, 'refused-operation-in-progress', `a ${state.operation} is in progress; finish or abort it first`);
+    }
+    if (await sources.git.hasUnmergedPaths()) {
+        return refuse(deps, 'refused-unmerged', 'unmerged paths exist; resolve them first');
+    }
+    // --- Step 5: a rewritten upstream must be reconciled (Decision 43) ---
+    if (record.code === 'UPSTREAM_REWRITTEN') {
+        const judgement = await judgeRewrittenUpstream(state.branchRef, input.acceptUpstream, sources, deps);
+        if (judgement.kind === 'refused') {
+            return judgement.result;
+        }
+    }
+    // --- Step 6: clear ---
+    await sources.halt.clear();
+    say(deps, `halt cleared (${describeRecord(record)})`);
+    return { exitCode: EXIT.OK, outcome: 'cleared' };
+}
+/**
+ * The comparison the next cycle makes (1.10 steps 6 and 7): the remote head,
+ * against the verified ref, or the tracking ref the cycle would seed it from
+ * when it is missing. With no reference point at all the next cycle has
+ * nothing to compare, so it cannot halt again.
+ */
+async function judgeRewrittenUpstream(branchRef, acceptUpstream, sources, deps) {
+    const upstream = branchRef === null ? null : await sources.git.upstream(branchRef);
+    if (branchRef === null || upstream === null) {
+        return unreachable(deps, 'the checked-out branch has no upstream to compare with');
+    }
+    const remoteHead = await sources.git.remoteHead(upstream.remote, upstream.remoteRef);
+    if (remoteHead.kind === 'unreachable') {
+        return unreachable(deps, `${upstream.remote} cannot be reached (${remoteHead.detail})`);
+    }
+    if (remoteHead.kind === 'absent') {
+        return unreachable(deps, `${upstream.remote} has no ${upstream.remoteRef}; enmetu never recreates a deleted remote branch`);
+    }
+    const remoteSha = remoteHead.sha;
+    // The objects must be local for the ancestry checks; the incoming ref is
+    // enmetu's own, so no person's ref moves.
+    const fetched = await sources.writer.fetch(upstream.remote, upstream.remoteRef, incomingRefFor(branchRef));
+    if (fetched.kind === 'failed') {
+        return unreachable(deps, `fetching ${upstream.remote} ${upstream.remoteRef} failed (${fetched.detail})`);
+    }
+    const verifiedRef = verifiedRefFor(branchRef);
+    const verifiedSha = await sources.git.resolveCommit(verifiedRef);
+    const referenceSha = verifiedSha ?? (await sources.git.resolveCommit(upstream.trackingRef));
+    if (referenceSha === null ||
+        referenceSha === remoteSha ||
+        (await sources.git.isAncestor(referenceSha, remoteSha))) {
+        return { kind: 'clear' };
+    }
+    if (!acceptUpstream) {
+        return refused(deps, 'refused-upstream-not-reconciled', `${upstream.remote} ${upstream.remoteRef} at ${remoteSha} still does not descend from ${referenceSha}; reconcile the branch with the rewritten upstream, then run: enmetu resume --accept-upstream`);
+    }
+    const head = await sources.git.headCommit();
+    if (head !== null && (await sources.git.isAncestor(referenceSha, head))) {
+        // The next rebase would replay the purged commits onto the new upstream.
+        return refused(deps, 'refused-history-still-local', `${branchRef} still contains ${referenceSha}, the history the force-push removed; rebase or reset the branch onto ${upstream.remote} ${upstream.remoteRef} first`);
+    }
+    await sources.writer.updateRef(verifiedRef, remoteSha, verifiedSha);
+    return { kind: 'clear' };
+}
+function unreachable(deps, reason) {
+    return refused(deps, 'refused-upstream-unreachable', reason);
+}
+function refused(deps, outcome, reason) {
+    return { kind: 'refused', result: refuse(deps, outcome, reason) };
+}
+/** Every refusal after the lock check keeps the marker and exits 3. */
+function refuse(deps, outcome, reason) {
+    say(deps, `resume refused: ${reason}; the halt stays`);
+    return { exitCode: EXIT.HALTED, outcome };
+}
+function describeRecord(record) {
+    return `${record.code} at ${record.at}: ${record.message}`;
+}
+function say(deps, text) {
+    deps.stdout.write(`enmetu: ${text}\n`);
+}

package/dist/cli/commands/runCommand.d.ts

@@ -0,0 +1,34 @@
+import type { EnmetuConfig } from '../../contracts/config.js';
+import { type ExitCode } from '../../contracts/exitCode.js';
+import type { IDaemon } from '../../contracts/IDaemon.js';
+import type { IFileSystem } from '../../contracts/IFileSystem.js';
+import type { ILogger } from '../../contracts/ILogger.js';
+import type { IRepositoryLocator, RepositoryPaths } from '../../contracts/IRepositoryLocator.js';
+export interface RunCommandInput {
+    /** --repo, else the working directory. */
+    readonly startDir: string;
+}
+export interface RunCommandDeps {
+    readonly locator: IRepositoryLocator;
+    readonly fs: IFileSystem;
+    readonly logger: ILogger;
+    /** Composition-root closure; builds the daemon for the resolved repository. */
+    readonly createDaemon: (paths: RepositoryPaths, config: EnmetuConfig) => IDaemon;
+}
+export interface RunCommandResult {
+    readonly exitCode: ExitCode;
+}
+/** Minimum git version (Decision 16): --no-update-refs appeared in 2.38. */
+export declare const MIN_GIT_VERSION: {
+    major: number;
+    minor: number;
+};
+/**
+ * Controller:
+ * 1. locator.locate(startDir): not a repository, bare, or PATH_UNSUPPORTED log NOT_ELIGIBLE, exit 5.
+ * 2. Git older than 2.38: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
+ * 3. parseConfig of <root>/enmetu.config.json: ConfigError logs CONFIG_INVALID, exit 2;
+ *    each unknown key logs CONFIG_KEY_IGNORED once and is ignored (design 14.17).
+ * 4. createDaemon(paths, config).run(), its exit code returned.
+ */
+export declare function runCommand(input: RunCommandInput, deps: RunCommandDeps): Promise<RunCommandResult>;

package/dist/cli/commands/runCommand.js

@@ -0,0 +1,79 @@
+import { join } from 'node:path';
+import { ConfigError, PreflightError, } from '../../contracts/errors.js';
+import { EXIT } from '../../contracts/exitCode.js';
+import { CONFIG_FILE_NAME, parseConfig } from '../../core/config/parseConfig.js';
+/** Minimum git version (Decision 16): --no-update-refs appeared in 2.38. */
+export const MIN_GIT_VERSION = { major: 2, minor: 38 };
+/**
+ * Controller:
+ * 1. locator.locate(startDir): not a repository, bare, or PATH_UNSUPPORTED log NOT_ELIGIBLE, exit 5.
+ * 2. Git older than 2.38: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
+ * 3. parseConfig of <root>/enmetu.config.json: ConfigError logs CONFIG_INVALID, exit 2;
+ *    each unknown key logs CONFIG_KEY_IGNORED once and is ignored (design 14.17).
+ * 4. createDaemon(paths, config).run(), its exit code returned.
+ */
+export async function runCommand(input, deps) {
+    // --- Step 1: the repository root through git, not the start directory (D9) ---
+    let location;
+    try {
+        location = await deps.locator.locate(input.startDir);
+    }
+    catch (error) {
+        if (error instanceof PreflightError) {
+            return notEligible(deps, error.code, error.message);
+        }
+        throw error;
+    }
+    if (location.kind === 'not-a-repository') {
+        return notEligible(deps, 'NOT_A_REPOSITORY', `${input.startDir} is not inside a git work tree`);
+    }
+    if (location.kind === 'bare') {
+        return notEligible(deps, 'BARE_REPOSITORY', `${input.startDir} is a bare repository; enmetu needs a work tree`);
+    }
+    const { paths, version } = location;
+    // --- Step 2: the git version gate ---
+    if (olderThanMinimum(version)) {
+        return notEligible(deps, 'GIT_TOO_OLD', `git ${version.major}.${version.minor}.${version.patch} is older than ${MIN_GIT_VERSION.major}.${MIN_GIT_VERSION.minor}`);
+    }
+    // --- Step 3: the config at the resolved root, defaults when absent ---
+    const configPath = join(paths.root, CONFIG_FILE_NAME);
+    let parsed;
+    try {
+        parsed = parseConfig(await deps.fs.readText(configPath));
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError)) {
+            throw error;
+        }
+        deps.logger.log({
+            level: 'ERROR',
+            code: 'CONFIG_INVALID',
+            message: `${configPath}: ${error.code}: ${error.message}`,
+        });
+        return { exitCode: EXIT.USAGE };
+    }
+    // A key only a newer enmetu knows must not stop this one (design 14.17).
+    for (const key of parsed.unknownKeys) {
+        deps.logger.log({
+            level: 'WARN',
+            code: 'CONFIG_KEY_IGNORED',
+            message: `${CONFIG_FILE_NAME}: unknown setting "${key}", ignored`,
+        });
+    }
+    const { config } = parsed;
+    // --- Step 4: the daemon for this repository ---
+    return { exitCode: await deps.createDaemon(paths, config).run() };
+}
+function olderThanMinimum(version) {
+    return (version.major < MIN_GIT_VERSION.major ||
+        (version.major === MIN_GIT_VERSION.major &&
+            version.minor < MIN_GIT_VERSION.minor));
+}
+function notEligible(deps, code, message) {
+    deps.logger.log({
+        level: 'ERROR',
+        code: 'NOT_ELIGIBLE',
+        message: `${code}: ${message}`,
+    });
+    return { exitCode: EXIT.NOT_ELIGIBLE };
+}

package/dist/cli/commands/statusCommand.d.ts

@@ -0,0 +1,71 @@
+import { type ExitCode } from '../../contracts/exitCode.js';
+import type { IGitReader } from '../../contracts/IGitReader.js';
+import type { IHaltStore } from '../../contracts/IHaltStore.js';
+import type { ILockInspector } from '../../contracts/IInstanceLock.js';
+import type { IOperationJournal } from '../../contracts/IOperationJournal.js';
+import type { IPathQuarantine } from '../../contracts/IPathQuarantine.js';
+import type { IRepositoryLocator, RepositoryPaths } from '../../contracts/IRepositoryLocator.js';
+import type { IStateStore } from '../../contracts/IStateStore.js';
+import type { ITextSink } from '../../contracts/ITextSink.js';
+import { type GuideLine } from '../../core/status/conflictGuide.js';
+/** Read-only views of one repository's state; status never writes and never contacts the remote. */
+export interface StatusSources {
+    readonly lock: ILockInspector;
+    readonly halt: IHaltStore;
+    readonly journal: IOperationJournal;
+    readonly quarantine: IPathQuarantine;
+    readonly git: IGitReader;
+    /** state.json, read for the headline, the state line and the conflict guide (design 12.2, 12.4). */
+    readonly state: IStateStore;
+}
+export interface StatusCommandInput {
+    readonly startDir: string;
+}
+export interface StatusCommandDeps {
+    readonly locator: IRepositoryLocator;
+    readonly openSources: (paths: RepositoryPaths) => StatusSources;
+    readonly stdout: ITextSink;
+}
+/** One value per printed line, in print order; the headline is printed without a label. */
+export interface StatusReport {
+    readonly headline: string;
+    readonly repository: string;
+    readonly instance: string;
+    readonly state: string;
+    readonly halt: string;
+    readonly recovery: string;
+    readonly branch: string;
+    readonly divergence: string;
+    readonly uncommitted: string;
+    /** One line per recorded orphaned commit still on no local branch (design 14.15); empty when none. */
+    readonly orphaned: readonly GuideLine[];
+    /** The conflict guide's lines after uncommitted (design 12.3); empty when no conflict is held at HEAD. */
+    readonly conflictGuide: readonly GuideLine[];
+}
+export interface StatusCommandResult {
+    readonly exitCode: ExitCode;
+    /** null when the start directory is not in an eligible repository. */
+    readonly report: StatusReport | null;
+}
+/** The uncommitted line names this many paths, then "and <n> more" (design 12.2). */
+export declare const MAX_UNCOMMITTED_PATHS = 20;
+/**
+ * Controller:
+ * 1. locator.locate(startDir); not found or bare: exit 5.
+ * 2. Gather the facts, all local (no network, no write): state.read(),
+ *    lock.inspect(), state.read() again, liveness judged with the second
+ *    record and the holder (Decision 86); halt.read(), journal.read(),
+ *    quarantine.hasPending(); branch and upstream, divergence against
+ *    trackingSha ?? verifiedSha (Decision 66); uncommitted paths from
+ *    git.status(), which runs with GIT_OPTIONAL_LOCKS=0, so no index write
+ *    (Decision 85). While a conflict is held at HEAD, the conflict guide
+ *    (design 12.3) from merge-base and two name-only diffs, which write no
+ *    object (Decision 67). Each recorded orphaned commit asked of git
+ *    (design 14.15).
+ * 3. Print the headline, then one labelled line per fact (design 1.18, 12.2:
+ *    state after instance, uncommitted after divergence, then the pending
+ *    orphaned commits, then the guide);
+ *    halted exits 3, else 0. The exit codes answer scripts and are unchanged
+ *    (Decision 66).
+ */
+export declare function statusCommand(input: StatusCommandInput, deps: StatusCommandDeps): Promise<StatusCommandResult>;