lockage 0.0.0-stage → 0.9.1

package/dist/hook/guard.js

@@ -0,0 +1,106 @@
+/**
+ * Decision for the main-working-tree edit guard. The input/output is normalized to the claude shape
+ * { tool_input, cwd, session_id } by each client's adapter (clients.ts) before being passed in.
+ *
+ * In a repository operating under lockage, if an edit targets a file in the main working tree rather
+ * than a worktree, interpose a confirmation. We use a confirmation instead of deny so as not to
+ * block the case where a person works on the main tree without using lockage (Kiro, which cannot
+ * show a confirmation, falls back to deny).
+ *
+ * The confirmation keeps appearing until it is allowed. Once allowed and the edit actually happens
+ * (PostToolUse), we no longer ask for that session and that repository. An operating repository
+ * always leaves traces such as a lockage/ branch or .lockage/, so asking every time would cause
+ * confirmation fatigue — leading to always allowing it, or disabling the guard entirely so it
+ * becomes a mere formality. We do not place the mark at PreToolUse time because the hook cannot
+ * distinguish allow from deny, which would let even a post-deny edit slip through.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { log, mainTreeRoot } from './repo.js';
+// Windows has no getuid. Do not crash on read; fall back to asking every time without using the mark (usableStateDir).
+const UID = typeof process.getuid === 'function' ? process.getuid() : null;
+// Where the "editing this repo's main working tree was allowed in this session" mark is placed. It
+// is the OS temp directory, so it is cleared on reboot. Linux's /tmp is shared across all users, so
+// separate it per user.
+export const STATE_DIR = process.env.LOCKAGE_GUARD_STATE_DIR || join(tmpdir(), `lockage-plugin-guard-${UID}`);
+/**
+ * true if a state directory writable only by us could be prepared.
+ *
+ * If another user created the same name first, they could place the mark and disable the guard, so
+ * we do not use it (we ask every time then). We also do not use it in an environment where we
+ * cannot verify ownership (no getuid).
+ */
+function usableStateDir(stateDir) {
+    if (UID === null)
+        return false;
+    let st;
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        st = statSync(stateDir);
+    }
+    catch (e) {
+        log(`Cannot prepare the state directory, so not using the confirmed record: ${String(e)}`);
+        return false;
+    }
+    if (st.uid !== UID || (st.mode & 0o077) !== 0) {
+        log(`The state directory is not exclusively ours, so not using the confirmed record: ${stateDir}`);
+        return false;
+    }
+    return true;
+}
+/** Resolve the main-working-tree edit target (the main repository root) from the payload. */
+function mainTreeTarget(payload) {
+    const toolInput = payload.tool_input ?? {};
+    const path = toolInput.file_path || toolInput.notebook_path;
+    if (!path)
+        return null;
+    return mainTreeRoot(path, payload.cwd ?? undefined);
+}
+/** Determine the mark file path from the session_id and the main repository path. */
+function markPath(sessionId, mainRoot, stateDir) {
+    const key = createHash('sha256').update(`${sessionId}\0${mainRoot}`).digest('hex');
+    return join(stateDir, key);
+}
+/**
+ * PreToolUse: returns the reason string if a confirmation should be interposed, or null if not.
+ */
+export function decide(payload, stateDir = STATE_DIR) {
+    const mainRoot = mainTreeTarget(payload);
+    if (mainRoot === null)
+        return null;
+    const sessionId = payload.session_id;
+    if (sessionId &&
+        usableStateDir(stateDir) &&
+        existsSyncSafe(markPath(sessionId, mainRoot, stateDir))) {
+        return null;
+    }
+    return (`${mainRoot} is a repository operating under lockage, and the edit targets its main working tree. ` +
+        'If you are working as a lockage task, edit inside the worktree_path returned by assign_worktree. ' +
+        'If you are editing the main tree directly as work that does not use lockage, go ahead and allow it. ' +
+        'If you allow it, this session will no longer confirm edits to this repository\'s main working tree.');
+}
+/**
+ * PostToolUse: record that an edit to the main working tree actually happened (= was allowed).
+ */
+export function record(payload, stateDir = STATE_DIR) {
+    const sessionId = payload.session_id;
+    if (!sessionId)
+        return; // when the session cannot be identified, do not record; ask every time
+    const mainRoot = mainTreeTarget(payload);
+    if (mainRoot === null || !usableStateDir(stateDir))
+        return;
+    closeSync(openSync(markPath(sessionId, mainRoot, stateDir), 'w'));
+}
+/** Check the mark file's existence (statSync throws on a nonexistent path, so swallow it). */
+function existsSyncSafe(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=guard.js.map

package/dist/hook/repo.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Repository and lockage state decisions shared by the hooks.
+ *
+ * Each client's adapter (claude / antigravity / kiro) calls this pure logic and only handles the
+ * input/output fitting (the adapters themselves are in clients.ts).
+ *
+ * Since a hook does not stop the work even if it fails, git uses a swallowing wrapper (git() below)
+ * that returns null for non-zero exit, timeout, or being outside git. The git in src/lockage/git.ts
+ * is throw-based and serves a different purpose, so it is not reused here.
+ */
+/**
+ * Repository state.
+ * in_use calls git, so it is split into the inUse(state) function to keep the policy of calling it
+ * only when needed.
+ */
+export interface RepoState {
+    mainRoot: string | null;
+    toplevel: string;
+    isLinked: boolean;
+    worktreeList: string;
+}
+/**
+ * Since a hook does not stop the work even if it fails, leave a clue on stderr when it silently
+ * becomes a no-op. Emits `[lockage-plugin] ...`.
+ */
+export declare function log(msg: string): void;
+/**
+ * Return whether the state has lockage operation traces.
+ * It calls git, so it is factored into a function to preserve the optimization where the caller
+ * (mainTreeRoot) looks at isLinked first and does not call it when unnecessary.
+ */
+export declare function inUse(state: RepoState): boolean;
+/**
+ * Derive the state of the repository containing path. null if it cannot be determined, e.g. outside a git repository.
+ */
+export declare function repoState(path: string): RepoState | null;
+/**
+ * If path is inside the main working tree of a repository operating under lockage, return that main repo's path.
+ */
+export declare function mainTreeRoot(path: string, cwd?: string): string | null;

package/dist/hook/repo.js

@@ -0,0 +1,173 @@
+/**
+ * Repository and lockage state decisions shared by the hooks.
+ *
+ * Each client's adapter (claude / antigravity / kiro) calls this pure logic and only handles the
+ * input/output fitting (the adapters themselves are in clients.ts).
+ *
+ * Since a hook does not stop the work even if it fails, git uses a swallowing wrapper (git() below)
+ * that returns null for non-zero exit, timeout, or being outside git. The git in src/lockage/git.ts
+ * is throw-based and serves a different purpose, so it is not reused here.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+// Per-git-call limit. We call git at most 3 times per repository (twice in repoState, once in
+// inUse), so keep the total under the hook timeout (10 seconds).
+const GIT_TIMEOUT_MS = 2000;
+/**
+ * Since a hook does not stop the work even if it fails, leave a clue on stderr when it silently
+ * becomes a no-op. Emits `[lockage-plugin] ...`.
+ */
+export function log(msg) {
+    process.stderr.write(`[lockage-plugin] ${msg}\n`);
+}
+/**
+ * The hook-only swallowing git wrapper. Runs `git -C <cwd> <args...>` and returns null for all of
+ * non-zero exit, timeout, and being outside git.
+ *
+ * execFileSync throws on both non-zero exit and timeout, so catch with try/catch.
+ * Log to stderr only on timeout (error.code === 'ETIMEDOUT' or error.killed).
+ */
+function git(cwd, ...args) {
+    try {
+        return execFileSync('git', ['-C', cwd, ...args], {
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === 'ETIMEDOUT' || err.killed) {
+            log(`git ${args[0]} did not finish within ${GIT_TIMEOUT_MS / 1000} seconds: ${cwd}`);
+        }
+        return null;
+    }
+}
+/**
+ * Walk up to the nearest existing parent directory.
+ * A file newly created via Write may not even have its parent directory yet. Returns null if it reaches the root.
+ */
+function nearestExistingDir(path) {
+    let d = isDir(path) ? path : dirname(path);
+    while (d && !isDir(d)) {
+        const parent = dirname(d);
+        if (parent === d)
+            return null;
+        d = parent;
+    }
+    return d || null;
+}
+/** Whether path is an existing directory (statSync throws on a nonexistent path, so swallow it). */
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * realpathSync may throw on a nonexistent path. We want to return a nonexistent path as-is, so if it
+ * throws, return the original path.
+ */
+function realpathSafe(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Return the main working tree. null if it cannot be derived.
+ *
+ * The head of the worktree list points to the main working tree. However, in a --separate-git-dir
+ * layout git itself does not remember the main working tree, and the .git entity (gitdir) appears at
+ * the head. A bare repo has no working tree.
+ *
+ * The "bare check" is done by exact-match membership against the line list. It is not a substring,
+ * so a worktree path containing the string bare is not misjudged.
+ */
+function mainWorktree(worktreeList, toplevel, isLinked) {
+    // Split the first block (up to the first blank line) into lines.
+    const firstBlock = worktreeList.split('\n\n', 1)[0];
+    const first = firstBlock.length === 0 ? [] : firstBlock.split('\n');
+    if (first.length > 0 && first[0].startsWith('worktree ') && !first.includes('bare')) {
+        const candidate = first[0].slice('worktree '.length);
+        if (existsSync(join(candidate, '.git'))) {
+            return candidate;
+        }
+    }
+    // If we are inside the main working tree, that is the main repo
+    return isLinked ? null : toplevel;
+}
+/**
+ * Whether there is evidence that lockage has been used in this repository.
+ * It calls git, so call it only when needed (the guard does not look for edits inside a worktree).
+ */
+function lockageInUse(toplevel, mainRoot, worktreeList) {
+    // Among the traces, look first at the one that survives worktree release (reconcile).
+    // release_worktree does not delete branches by default, so branches under lockage/ remain the longest
+    const refs = git(toplevel, 'for-each-ref', '--count=1', '--format=x', 'refs/heads/lockage/');
+    if (refs)
+        return true;
+    // assign_worktree digs a worktree under <repo parent>/.lockage-worktrees/
+    if (worktreeList.includes('/.lockage-worktrees/'))
+        return true;
+    // Treat a .lockage/ directly under the main working tree as a supplementary trace.
+    // The .lockage/ in the home directory is where lockage's ledger DB lives, so do not count it.
+    if (mainRoot === null || realpathSafe(mainRoot) === realpathSafe(homedir())) {
+        return false;
+    }
+    return isDir(join(mainRoot, '.lockage'));
+}
+/**
+ * Return whether the state has lockage operation traces.
+ * It calls git, so it is factored into a function to preserve the optimization where the caller
+ * (mainTreeRoot) looks at isLinked first and does not call it when unnecessary.
+ */
+export function inUse(state) {
+    return lockageInUse(state.toplevel, state.mainRoot, state.worktreeList);
+}
+/**
+ * Derive the state of the repository containing path. null if it cannot be determined, e.g. outside a git repository.
+ */
+export function repoState(path) {
+    const d = nearestExistingDir(resolve(path));
+    if (d === null)
+        return null;
+    const out = git(d, 'rev-parse', '--path-format=absolute', '--show-toplevel', '--git-dir', '--git-common-dir');
+    if (out === null)
+        return null; // outside a git repository
+    if (out.startsWith('--')) {
+        // git before 2.31 does not know --path-format and, instead of erroring, prints it as-is and
+        // succeeds. The subsequent lines shift by one and return wrong paths, so give up the decision here
+        log(`git rev-parse did not interpret --path-format (possibly git before 2.31): ${d}`);
+        return null;
+    }
+    const lines = out.split('\n').filter((_, i, arr) => i < arr.length - 1 || arr[i].length > 0);
+    if (lines.length < 3)
+        return null; // no working tree, e.g. inside a bare repository
+    const [toplevel, gitDir, commonDir] = lines;
+    // Do not use commonDir's parent directory: in submodule, --separate-git-dir, or bare + worktree
+    // layouts it does not point to the main repo
+    const isLinked = realpathSafe(gitDir) !== realpathSafe(commonDir);
+    const worktreeList = git(toplevel, 'worktree', 'list', '--porcelain') ?? '';
+    const mainRoot = mainWorktree(worktreeList, toplevel, isLinked);
+    return { mainRoot, toplevel, isLinked, worktreeList };
+}
+/**
+ * If path is inside the main working tree of a repository operating under lockage, return that main repo's path.
+ */
+export function mainTreeRoot(path, cwd) {
+    const abs = isAbsolute(path) ? path : join(cwd ?? process.cwd(), path);
+    const st = repoState(abs);
+    // Look at isLinked first. For edits inside a worktree (the most common path) this skips the inUse git call
+    if (st === null || st.isLinked || !inUse(st)) {
+        return null;
+    }
+    return st.mainRoot;
+}
+//# sourceMappingURL=repo.js.map

package/dist/hook/setup-kiro.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The body of `lockage setup kiro`. Generates lockage-guard.json and lockage-session.json in the
+ * target repository's .kiro/hooks/ with npx-form commands (folding in a manual copy + absolute-path
+ * substitution).
+ *
+ * design.md §5 is authoritative. The install base is mainRoot ?? toplevel (the main repository root)
+ * from running --repo (default cwd) through repoState. If repoState is null (outside git), it is
+ * directly under --repo's real path. Even when run inside a worktree, the correct place for the hook
+ * is the main repository, so it is generated in .kiro/hooks/ directly under the main root.
+ *
+ * The outer schema of the generated JSON is identical to the bundled templates plugins/kiro/hooks/*.json
+ * (version/name/trigger/matcher/action). Kiro reads the hook via this outer shape, so dropping the
+ * structure makes it silently a no-op.
+ */
+/** Options for setup kiro. */
+export interface SetupKiroOptions {
+    repo?: string;
+    force?: boolean;
+}
+/** The result of setup kiro (dispatch.ts maps it to an exit code). */
+export interface SetupKiroResult {
+    exitCode: number;
+    lines: string[];
+}
+/**
+ * The body of setup kiro. Creates .kiro/hooks/ and generates lockage-guard.json / lockage-session.json.
+ * A mkdir/write failure or a --repo pointing to a nonexistent directory throws (the outermost shell
+ * in dispatch.ts turns it into stderr + non-zero).
+ */
+export declare function setupKiro(opts: SetupKiroOptions): SetupKiroResult;

package/dist/hook/setup-kiro.js

@@ -0,0 +1,118 @@
+/**
+ * The body of `lockage setup kiro`. Generates lockage-guard.json and lockage-session.json in the
+ * target repository's .kiro/hooks/ with npx-form commands (folding in a manual copy + absolute-path
+ * substitution).
+ *
+ * design.md §5 is authoritative. The install base is mainRoot ?? toplevel (the main repository root)
+ * from running --repo (default cwd) through repoState. If repoState is null (outside git), it is
+ * directly under --repo's real path. Even when run inside a worktree, the correct place for the hook
+ * is the main repository, so it is generated in .kiro/hooks/ directly under the main root.
+ *
+ * The outer schema of the generated JSON is identical to the bundled templates plugins/kiro/hooks/*.json
+ * (version/name/trigger/matcher/action). Kiro reads the hook via this outer shape, so dropping the
+ * structure makes it silently a no-op.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { repoState } from './repo.js';
+/** Build the contents of lockage-guard.json (2 PreToolUse matchers; no --agents-md). */
+function guardDef() {
+    const command = 'npx -y lockage hook guard --client kiro';
+    return {
+        version: 'v1',
+        hooks: [
+            {
+                name: 'lockage-guard-fs-write',
+                trigger: 'PreToolUse',
+                matcher: 'fs_write',
+                action: { type: 'command', command },
+            },
+            {
+                name: 'lockage-guard-str-replace',
+                trigger: 'PreToolUse',
+                matcher: 'str_replace',
+                action: { type: 'command', command },
+            },
+        ],
+    };
+}
+/** Build the contents of lockage-session.json (1 SessionStart hook; embed base's steering path in --agents-md). */
+function sessionDef(base) {
+    const agentsMd = join(base, '.kiro', 'steering', 'AGENTS.md');
+    return {
+        version: 'v1',
+        hooks: [
+            {
+                name: 'lockage-session',
+                trigger: 'SessionStart',
+                action: {
+                    type: 'command',
+                    command: `npx -y lockage hook session --client kiro --agents-md "${agentsMd}"`,
+                },
+            },
+        ],
+    };
+}
+/** Turn the JSON into formatted text with a trailing newline (use the same formatting for existing-file comparison and writing). */
+function serialize(def) {
+    return JSON.stringify(def, null, 2) + '\n';
+}
+/** Generate/compare one file. Returns the result (created/updated/unchanged/skipped-needs-force). */
+function writeHookFile(path, content, force) {
+    if (existsSync(path)) {
+        const existing = readFileSync(path, { encoding: 'utf8' });
+        if (existing === content)
+            return 'unchanged';
+        if (!force)
+            return 'skipped-needs-force';
+        writeFileSync(path, content);
+        return 'updated';
+    }
+    writeFileSync(path, content);
+    return 'created';
+}
+/**
+ * Derive the install base directory. mainRoot ?? toplevel from running --repo (default cwd) through
+ * repoState; if repoState is null, directly under --repo's real path (§5). Throws if --repo is a
+ * nonexistent directory.
+ */
+function resolveBase(repo) {
+    const abs = resolve(repo);
+    // A --repo pointing to a nonexistent directory is fatal (stderr + non-zero)
+    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+        throw new Error(`--repo is not an existing directory: ${abs}`);
+    }
+    const st = repoState(abs);
+    if (st === null)
+        return abs; // can also be placed in a directory outside git
+    return st.mainRoot ?? st.toplevel;
+}
+/**
+ * The body of setup kiro. Creates .kiro/hooks/ and generates lockage-guard.json / lockage-session.json.
+ * A mkdir/write failure or a --repo pointing to a nonexistent directory throws (the outermost shell
+ * in dispatch.ts turns it into stderr + non-zero).
+ */
+export function setupKiro(opts) {
+    const base = resolveBase(opts.repo ?? process.cwd());
+    const force = opts.force ?? false;
+    const hooksDir = join(base, '.kiro', 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    const targets = [
+        { path: join(hooksDir, 'lockage-guard.json'), content: serialize(guardDef()) },
+        { path: join(hooksDir, 'lockage-session.json'), content: serialize(sessionDef(base)) },
+    ];
+    const lines = [];
+    let needsForce = false;
+    for (const { path, content } of targets) {
+        const result = writeHookFile(path, content, force);
+        if (result === 'skipped-needs-force') {
+            needsForce = true;
+            lines.push(`${path}: skipped-needs-force (differs from the existing file; overwrite with --force)`);
+        }
+        else {
+            lines.push(`${path}: ${result}`);
+        }
+    }
+    return { exitCode: needsForce ? 1 : 0, lines };
+}
+//# sourceMappingURL=setup-kiro.js.map

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type CoordDb } from './db/index.js';
+/** Shared helper that returns a tool result as MCP text content (JSON). */
+declare function ok(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+declare function fail(message: string): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * Toolsets not registered by default (#65). Enabled at server startup via the LOCKAGE_TOOLSETS
+ * environment variable (comma-separated). Tools that belong to no toolset (core) are always
+ * registered. lockage-publish also uses core tools such as read_ticket and list_tasks, so there
+ * is no option to drop core.
+ *
+ * - publisher: cleanup tools called only by lockage-publish. If an agent calls them it could
+ *   close tickets or clear integration branch names, so they are not shown in the agent's list.
+ * - maintenance: for maintenance/diagnostics. Enabled only when a human needs it.
+ *
+ * The actual registration split is the `if (toolsets.has(...))` in buildServer; this list exists
+ * to cross-check that against the README (drift is detected by tests). We do not register
+ * everything and then remove some, because the MCP SDK has no public API to look up a registered
+ * tool by name and remove it.
+ */
+export declare const OPTIONAL_TOOLSETS: {
+    readonly publisher: readonly ["acquire_publish_lock", "release_publish_lock", "clear_integration_branch", "close_ticket_on_merge", "release_ticket_worktrees", "release_ticket_claims"];
+    readonly maintenance: readonly ["reclaim_orphan_worktrees", "process_merge_queue", "list_merge_queue"];
+};
+export type OptionalToolset = keyof typeof OPTIONAL_TOOLSETS;
+/**
+ * Turns the LOCKAGE_TOOLSETS value into a set of toolsets. `core` is always enabled, so it is
+ * ignored even if written. An unknown name is a configuration error (e.g. a typo), so instead of
+ * silently ignoring it we stop startup.
+ */
+export declare function parseToolsets(value: string | undefined): Set<OptionalToolset>;
+export declare function buildServer(cdb: CoordDb, opts?: {
+    toolsets?: Iterable<OptionalToolset>;
+}): McpServer;
+export { fail, ok };