@njeybe/nativ 2.0.0

package/dist/core/lock-manager.js

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import pc from 'picocolors';
+export const DEFAULT_LOCK_OPTIONS = {
+    stale: 10000, // 10 seconds stale timeout prevents deadlocks if a process crashes
+    retries: {
+        retries: 40,
+        factor: 1.2,
+        minTimeout: 20,
+        maxTimeout: 500,
+    },
+    realpath: false, // Prevents symlink/junction resolution mismatch in git worktrees
+};
+/**
+ * Executes an operation holding an advisory lock on a given file.
+ * Automatically releases the lock when the operation finishes (even on error).
+ */
+export async function withFileLock(filePath, fn, options = {}) {
+    const mergedOptions = { ...DEFAULT_LOCK_OPTIONS, ...options };
+    // proper-lockfile requires the target file to exist
+    if (!fs.existsSync(filePath)) {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, '', 'utf8');
+    }
+    const release = await lockfile.lock(filePath, mergedOptions);
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            await release();
+        }
+        catch {
+            // Best-effort release (in case lock was already freed or invalidated)
+        }
+    }
+}
+/**
+ * Loads a master plan from disk without acquiring an advisory lock.
+ * Includes automatic transient retries to handle atomic file swap collisions (e.g. Windows EBUSY).
+ * Returns null if the file does not exist or fails to parse.
+ */
+export function loadPlan(planPath, options = {}) {
+    if (!fs.existsSync(planPath)) {
+        if (!options.silent) {
+            console.error(pc.red(`\n✖ No .ai/master_plan.json found at: ${planPath}`));
+            console.log(pc.yellow('Run `nativ init` first to scaffold the workflow.\n'));
+        }
+        return null;
+    }
+    const maxAttempts = options.retries ?? 10;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            const raw = fs.readFileSync(planPath, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            if (attempt === maxAttempts - 1) {
+                if (!options.silent) {
+                    console.error(pc.red(`\n✖ Failed to parse .ai/master_plan.json: ${err.message}\n`));
+                }
+                return null;
+            }
+            // Brief synchronous pause to allow concurrent rename to finalize
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+        }
+    }
+    return null;
+}
+/**
+ * Atomically writes the plan using a temp file rename with Windows EPERM/EBUSY resilience.
+ * Creates a unique temp file to prevent rename collisions across threads/processes.
+ */
+export function savePlan(planPath, plan) {
+    const tmpPath = `${planPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    try {
+        plan.lastUpdated = new Date().toISOString();
+        fs.writeFileSync(tmpPath, JSON.stringify(plan, null, 2) + '\n', 'utf8');
+        // Windows NTFS atomic rename retry loop
+        let renamed = false;
+        for (let attempt = 0; attempt < 10; attempt++) {
+            try {
+                fs.renameSync(tmpPath, planPath);
+                renamed = true;
+                break;
+            }
+            catch (err) {
+                if (err.code === 'EPERM' || err.code === 'EBUSY') {
+                    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        if (!renamed) {
+            // Fallback: direct atomic copyFileSync + unlinkSync under advisory lock
+            fs.copyFileSync(tmpPath, planPath);
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // Best-effort cleanup of temp file
+            }
+        }
+        return true;
+    }
+    catch (err) {
+        fs.rmSync(tmpPath, { force: true });
+        console.error(pc.red(`\n✖ Failed to save .ai/master_plan.json: ${err.message}\n`));
+        return false;
+    }
+}
+/**
+ * Safely executes a mutation on master_plan.json under an OS-level advisory lock.
+ * Ensures an atomic Read-Modify-Write cycle across concurrent agent processes.
+ */
+export async function withPlanLock(planPath, mutator, options = {}) {
+    if (!fs.existsSync(planPath)) {
+        console.error(pc.red(`\n✖ No .ai/master_plan.json found at: ${planPath}`));
+        console.log(pc.yellow('Run `nativ init` first to scaffold the workflow.\n'));
+        return null;
+    }
+    return withFileLock(planPath, async () => {
+        const plan = loadPlan(planPath);
+        if (!plan) {
+            console.error(pc.red(`\n✖ Failed to parse .ai/master_plan.json at: ${planPath}\n`));
+            return null;
+        }
+        let aborted = false;
+        const ctx = {
+            abort: () => {
+                aborted = true;
+            },
+            isAborted: () => aborted,
+        };
+        const result = await mutator(plan, ctx);
+        if (!aborted) {
+            savePlan(planPath, plan);
+        }
+        return result;
+    }, options);
+}
+/**
+ * Synchronous counterpart of withFileLock for callers that cannot await (the governor runs inside
+ * synchronous verdicts). Uses the same `<file>.lock` directory, so it excludes async holders too.
+ */
+export function withFileLockSync(filePath, fn, options = {}) {
+    const { retries: _ignored, ...syncOptions } = { ...DEFAULT_LOCK_OPTIONS, ...options };
+    if (!fs.existsSync(filePath)) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, '', 'utf8');
+    }
+    let release = null;
+    // ~5s of contention before giving up: parallel agents trip the breaker at the same moment.
+    const maxAttempts = 200;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            release = lockfile.lockSync(filePath, syncOptions);
+            break;
+        }
+        catch (err) {
+            if (attempt === maxAttempts - 1 || err.code !== 'ELOCKED')
+                throw err;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            release?.();
+        }
+        catch {
+            // Best-effort release
+        }
+    }
+}
+/**
+ * Writes JSON through a unique temp file and a rename, so readers never observe a half-written
+ * file. Retries the rename on Windows sharing violations, like savePlan().
+ */
+export function writeJsonAtomicSync(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    try {
+        for (let attempt = 0;; attempt++) {
+            try {
+                fs.renameSync(tmpPath, filePath);
+                return;
+            }
+            catch (err) {
+                if (attempt >= 10 || (err.code !== 'EPERM' && err.code !== 'EBUSY'))
+                    throw err;
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+            }
+        }
+    }
+    catch (err) {
+        fs.rmSync(tmpPath, { force: true });
+        throw err;
+    }
+}
+/**
+ * Synchronous variant of withPlanLock using proper-lockfile lockSync.
+ */
+export function withPlanLockSync(planPath, mutator, options = {}) {
+    if (!fs.existsSync(planPath)) {
+        return null;
+    }
+    const { retries: _ignored, ...syncOptions } = { ...DEFAULT_LOCK_OPTIONS, ...options };
+    let release = null;
+    const maxAttempts = 15;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            release = lockfile.lockSync(planPath, syncOptions);
+            break;
+        }
+        catch (err) {
+            if (attempt === maxAttempts - 1 || err.code !== 'ELOCKED') {
+                throw err;
+            }
+            // Brief synchronous pause
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+    }
+    if (!release)
+        return null;
+    try {
+        const plan = loadPlan(planPath, { silent: true });
+        if (!plan)
+            return null;
+        let aborted = false;
+        const ctx = {
+            abort: () => {
+                aborted = true;
+            },
+            isAborted: () => aborted,
+        };
+        const result = mutator(plan, ctx);
+        if (!aborted) {
+            savePlan(planPath, plan);
+        }
+        return result;
+    }
+    finally {
+        try {
+            release();
+        }
+        catch {
+            // Best-effort release
+        }
+    }
+}

package/dist/core/root-resolver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Resolves the primary project root containing the .ai/ contract specifications.
+ * When running inside an isolated Git worktree (.worktrees/task-*), this safely
+ * climbs back to the parent repository root so contracts, master plans, and
+ * schemas remain accessible to sub-agents.
+ */
+export declare function resolveProjectRoot(startDirArg?: string): string;
+/**
+ * Creates a directory junction (Windows) or symlink (Unix) linking .ai/
+ * from the main project root into the newly created worktree so path-relative
+ * agent tools continue to work seamlessly.
+ */
+export declare function linkWorktreeAiDirectory(worktreeDir: string, rootDir: string): boolean;
+/**
+ * Safely unlinks the .ai junction/symlink in a worktree directory before
+ * Git or filesystem deletion touches it. On Windows, recursive deletion of an untracked
+ * junction by tools like `git worktree remove --force` can traverse into the junction and
+ * delete original files in the project root. This guarantees only the link itself is removed.
+ */
+export declare function safeUnlinkWorktreeAiDirectory(worktreeDir: string): boolean;
+/**
+ * Creates a directory junction (Windows) or symlink (Unix) linking node_modules/
+ * from the main project root into the newly created worktree so sub-agents have
+ * access to project dependencies without running npm install in each worktree.
+ */
+export declare function linkWorktreeNodeModules(worktreeDir: string, rootDir: string): boolean;
+/**
+ * Safely unlinks the node_modules junction/symlink in a worktree directory before
+ * Git or filesystem deletion touches it, ensuring original node_modules in the
+ * project root are never deleted.
+ */
+export declare function safeUnlinkWorktreeNodeModules(worktreeDir: string): boolean;

package/dist/core/root-resolver.js

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Resolves the primary project root containing the .ai/ contract specifications.
+ * When running inside an isolated Git worktree (.worktrees/task-*), this safely
+ * climbs back to the parent repository root so contracts, master plans, and
+ * schemas remain accessible to sub-agents.
+ */
+export function resolveProjectRoot(startDirArg) {
+    let current = path.resolve(startDirArg || process.cwd());
+    // 1. Direct hit: .ai exists in the current directory
+    if (fs.existsSync(path.join(current, '.ai'))) {
+        return current;
+    }
+    // 2. Worktree directory convention (.worktrees/task-*)
+    const worktreeIdx = current.indexOf(path.join('.worktrees'));
+    if (worktreeIdx !== -1) {
+        const candidate = current.substring(0, worktreeIdx).replace(/[\\/]$/, '');
+        if (fs.existsSync(path.join(candidate, '.ai'))) {
+            return candidate;
+        }
+    }
+    // 3. Git worktree file inspection: in worktrees, .git is a file containing "gitdir: <path>"
+    const gitPath = path.join(current, '.git');
+    if (fs.existsSync(gitPath)) {
+        try {
+            const stat = fs.lstatSync(gitPath);
+            if (stat.isFile()) {
+                const content = fs.readFileSync(gitPath, 'utf8').trim();
+                const match = content.match(/^gitdir:\s*(.+)$/i);
+                if (match) {
+                    let gitDir = match[1].trim();
+                    if (!path.isAbsolute(gitDir)) {
+                        gitDir = path.resolve(current, gitDir);
+                    }
+                    // gitDir points to /path/to/repo/.git/worktrees/task-xxx
+                    // Main repo is 2 levels up from the worktrees metadata folder
+                    const mainRepo = path.resolve(gitDir, '..', '..');
+                    if (fs.existsSync(path.join(mainRepo, '.ai'))) {
+                        return mainRepo;
+                    }
+                }
+            }
+        }
+        catch {
+            // Fall through to traversal
+        }
+    }
+    // 4. Upward traversal fallback (climb until we find .ai or filesystem root)
+    let prev = '';
+    while (current && current !== prev) {
+        if (fs.existsSync(path.join(current, '.ai'))) {
+            return current;
+        }
+        prev = current;
+        current = path.dirname(current);
+    }
+    return path.resolve(startDirArg || process.cwd());
+}
+/**
+ * Creates a directory junction (Windows) or symlink (Unix) linking .ai/
+ * from the main project root into the newly created worktree so path-relative
+ * agent tools continue to work seamlessly.
+ */
+export function linkWorktreeAiDirectory(worktreeDir, rootDir) {
+    const rootAi = path.join(rootDir, '.ai');
+    const targetAi = path.join(worktreeDir, '.ai');
+    if (!fs.existsSync(rootAi) || fs.existsSync(targetAi)) {
+        return false;
+    }
+    try {
+        const isWindows = process.platform === 'win32';
+        fs.symlinkSync(rootAi, targetAi, isWindows ? 'junction' : 'dir');
+        return true;
+    }
+    catch {
+        // If symlinks fail (restricted permissions), we can copy or rely on resolveProjectRoot
+        return false;
+    }
+}
+/**
+ * Safely unlinks the .ai junction/symlink in a worktree directory before
+ * Git or filesystem deletion touches it. On Windows, recursive deletion of an untracked
+ * junction by tools like `git worktree remove --force` can traverse into the junction and
+ * delete original files in the project root. This guarantees only the link itself is removed.
+ */
+export function safeUnlinkWorktreeAiDirectory(worktreeDir) {
+    const targetAi = path.join(worktreeDir, '.ai');
+    try {
+        const stat = fs.lstatSync(targetAi);
+        if (stat.isSymbolicLink() || (process.platform === 'win32' && stat.isDirectory())) {
+            try {
+                fs.unlinkSync(targetAi);
+            }
+            catch {
+                fs.rmdirSync(targetAi);
+            }
+            return true;
+        }
+    }
+    catch {
+        // If it doesn't exist or isn't a link, ignore
+    }
+    return false;
+}
+/**
+ * Creates a directory junction (Windows) or symlink (Unix) linking node_modules/
+ * from the main project root into the newly created worktree so sub-agents have
+ * access to project dependencies without running npm install in each worktree.
+ */
+export function linkWorktreeNodeModules(worktreeDir, rootDir) {
+    const rootModules = path.join(rootDir, 'node_modules');
+    const targetModules = path.join(worktreeDir, 'node_modules');
+    if (!fs.existsSync(rootModules) || fs.existsSync(targetModules)) {
+        return false;
+    }
+    try {
+        const isWindows = process.platform === 'win32';
+        fs.symlinkSync(rootModules, targetModules, isWindows ? 'junction' : 'dir');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Safely unlinks the node_modules junction/symlink in a worktree directory before
+ * Git or filesystem deletion touches it, ensuring original node_modules in the
+ * project root are never deleted.
+ */
+export function safeUnlinkWorktreeNodeModules(worktreeDir) {
+    const targetModules = path.join(worktreeDir, 'node_modules');
+    try {
+        const stat = fs.lstatSync(targetModules);
+        if (stat.isSymbolicLink() || (process.platform === 'win32' && stat.isDirectory())) {
+            try {
+                fs.unlinkSync(targetModules);
+            }
+            catch {
+                fs.rmdirSync(targetModules);
+            }
+            return true;
+        }
+    }
+    catch {
+        // If it doesn't exist or isn't a link, ignore
+    }
+    return false;
+}

package/dist/core/setup-assets.d.ts

@@ -0,0 +1,123 @@
+/**
+ * nativ · Single source for every file `nativ setup` generates.
+ *
+ * `planSetup` computes what each asset should contain and whether that differs from disk; `applySetup`
+ * writes the differences; `nativ doctor` reuses the same plan to detect drift. Everything merges into
+ * existing files: user-authored settings, servers and agent files are never overwritten.
+ */
+import { type EnforcementMode } from './enforcement.js';
+export declare const MCP_SERVER_NAME = "nativ";
+export declare const AGENT_FILES: readonly ["architect.md", "worker.md", "verifier.md"];
+export type AssetAction = 'created' | 'updated' | 'unchanged' | 'skipped';
+export interface AssetChange {
+    /** Path relative to the project root, forward slashes. */
+    path: string;
+    action: AssetAction;
+    detail?: string;
+}
+export interface CliInvocation {
+    command: string;
+    prefixArgs: string[];
+    /** False when the command embeds an absolute path, which will not work on another machine. */
+    portable: boolean;
+}
+export interface SetupOptions {
+    /** How Claude Code should invoke nativ, e.g. `npx -y @njeybe/nativ`. Defaults to `nativ` when it is on PATH. */
+    command?: string;
+    enforcement?: EnforcementMode;
+    /** Also overwrite agent files that were edited by hand or are not nativ's. */
+    force?: boolean;
+    hasBinary?: (name: string) => boolean;
+    templatesDir?: string;
+}
+export interface SetupPlan {
+    root: string;
+    invocation: CliInvocation;
+    changes: AssetChange[];
+    warnings: string[];
+    /** Full new content per changed path, keyed by the same relative path. */
+    writes: Map<string, string>;
+}
+export declare function defaultHasBinary(name: string): boolean;
+export declare function resolveCliInvocation(options?: {
+    command?: string;
+    hasBinary?: (name: string) => boolean;
+}): CliInvocation;
+/** The invocation as a shell string, e.g. `npx -y @njeybe/nativ`, quoting parts that need it. */
+export declare function cliString(invocation: CliInvocation): string;
+export interface DesiredClaudeConfig {
+    cli: string;
+    mcpServer: {
+        command: string;
+        args: string[];
+    };
+    allow: string[];
+    deny: string[];
+    ask: string[];
+    preToolUse: {
+        matcher: string;
+        command: string;
+        timeout: number;
+    };
+    sessionStart: {
+        matcher: string;
+        command: string;
+        timeout: number;
+    };
+}
+export declare function buildDesiredConfig(invocation: CliInvocation): DesiredClaudeConfig;
+type Json = Record<string, unknown>;
+export interface MergeResult {
+    merged: Json;
+    changes: string[];
+    warnings: string[];
+}
+export declare function mergeClaudeSettings(existing: Json, desired: DesiredClaudeConfig): MergeResult;
+export declare function mergeMcpConfig(existing: Json, desired: DesiredClaudeConfig): {
+    merged: Json;
+    changed: boolean;
+};
+/** CRLF and a leading BOM to plain LF. */
+export declare const toLf: (text: string) => string;
+/** Appends the marker that lets a later run tell "nativ wrote this, untouched" from "a person edited this". */
+export declare function stampManaged(content: string): string;
+export type ManagedState = 'pristine' | 'modified' | 'unmanaged';
+export declare function managedState(content: string): ManagedState;
+export interface TemplateFilePlan {
+    action: AssetAction;
+    detail?: string;
+    /** The stamped content to write; absent when nothing should change. */
+    content?: string;
+}
+/**
+ * Decides what to do with a file derived from a template (a directive or a role guide).
+ * Missing files are created; files nativ wrote and nobody edited (marker intact, or matching a template nativ
+ * shipped before markers existed) follow the template; anything edited by hand is kept unless `force` is set.
+ * `legacyKey` names the file in LEGACY_TEMPLATE_HASHES.
+ */
+export declare function planTemplateFile(existing: string | null, template: string, legacyKey: string, force?: boolean): TemplateFilePlan;
+export declare function getTemplatesDir(): string;
+/**
+ * The command already registered for the nativ MCP server in `.mcp.json`, when it has the shape setup writes
+ * (`<command> <args...> mcp`). Reusing it keeps hooks and permissions in step with what the project chose, so a
+ * plain `nativ setup` or `nativ doctor --fix` never silently swaps a deliberate `--command` for auto-detection.
+ */
+export declare function configuredInvocation(root: string): CliInvocation | null;
+/** Computes what `nativ setup` would do, without touching disk. */
+export declare function planSetup(rootArg: string, options?: SetupOptions): SetupPlan;
+export interface SetupResult {
+    root: string;
+    dryRun: boolean;
+    invocation: CliInvocation;
+    changes: AssetChange[];
+    warnings: string[];
+}
+/** Writes the planned differences. Idempotent: applying twice changes nothing the second time. */
+export declare function applySetup(rootArg: string, options?: SetupOptions & {
+    dryRun?: boolean;
+}): SetupResult;
+/** A few lines of orientation for a new Claude Code session, or null when this is not a nativ project. */
+export declare function buildSessionContext(cwd: string, env?: NodeJS.ProcessEnv): string | null;
+/** `nativ hook context`: prints the SessionStart hook output. Never throws and always prints valid JSON or nothing. */
+export declare function runSessionContext(targetDirArg?: string, write?: (text: string) => void): void;
+export {};