javi-forge 1.38.6 → 1.39.1

package/assets/claude-hooks/javi-forge-skillguard-pre-tool-use.mjs

@@ -792,12 +792,63 @@ function bashSubstitutions(command) {
 	}
 	return bodies;
 }
+// This deliberately recognizes only a direct, quoted Python stdin heredoc on
+// the first command line. It removes the opaque body before shell inspection;
+// it does not parse Python or permit its execution.
+function pythonQuotedHeredoc(command) {
+	const newline = command.indexOf("\n");
+	const header = newline < 0 ? command : command.slice(0, newline);
+	const starts = [0];
+	let quote = "", escaped = false, heredocs = 0;
+	for (let index = 0; index < header.length; index++) {
+		const char = header[index];
+		if (escaped) { escaped = false; continue; }
+		if (char === "\\" && quote !== "'") { escaped = true; continue; }
+		if (quote) { if (char === quote) quote = ""; continue; }
+		if (char === "'" || char === '"' || char === "`") { quote = char; continue; }
+		if (char === "<" && header[index + 1] === "<") { heredocs++; index++; }
+		if (char === ";" || char === "|" || char === "&") starts.push(index + 1);
+	}
+	const literalPath = String.raw`(?:[A-Za-z0-9_./~-]+|'[A-Za-z0-9_./~ -]+'|"[A-Za-z0-9_./~ -]+")`;
+	const redirection = String.raw`(?:[0-9]*>>?|[0-9]*<)[ \t]*${literalPath}[ \t]*`;
+	const python = String.raw`[ \t]*(?:python3?|/(?:[A-Za-z0-9_.-]+/)*python3?)(?:[ \t]+-)?[ \t]*`;
+	const pattern = new RegExp(String.raw`^(${python}(?:${redirection})*)<<(-?)[ \t]*(['"])([A-Za-z_][A-Za-z0-9_]*)\3([ \t]*(?:${redirection})*)([;|&].*)?$`);
+	for (const start of starts) {
+		const match = pattern.exec(header.slice(start));
+		if (!match) continue;
+		// Multiple documents and tab-stripping need a shell grammar this guard
+		// intentionally does not implement, so retain fail-closed behavior.
+		if (newline < 0 || heredocs !== 1 || match[2]) fail("unlexable-command");
+		if (match[6]?.trimStart().startsWith("|")) fail("unlexable-command");
+		let offset = newline + 1;
+		while (offset <= command.length) {
+			const end = command.indexOf("\n", offset);
+			const lineEnd = end < 0 ? command.length : end;
+			if (command.slice(offset, lineEnd) === match[4]) {
+				const outerHeader = header.slice(0, start) + match[1] + match[5] + (match[6] ?? "");
+				return { command: `${outerHeader}\n${command.slice(lineEnd + 1)}`, unsupported: true };
+			}
+			if (end < 0) break;
+			offset = end + 1;
+		}
+		fail("unlexable-command");
+	}
+	return { command, unsupported: false };
+}
 function evaluateBash(command, cwd, config = AGENT_CONFIGS.claude, projectRoot = PROJECT_ROOT, depth = 0) {
 	if (depth > 4) return { allowed: false, ruleId: "shell.obfuscated-interpreter" };
+	let unsupported = false;
+	try { ({ command, unsupported } = pythonQuotedHeredoc(command)); } catch { return { allowed: false, ruleId: "shell.obfuscated-interpreter" }; }
 	const headerOnlyCommand = opaqueInertCatHereDoc(command, cwd, config, projectRoot);
 	if (headerOnlyCommand === null) return { allowed: false, ruleId: "shell.obfuscated-interpreter" };
 	command = headerOnlyCommand;
-	try { for (const body of bashSubstitutions(command)) { const nested = evaluateBash(body, cwd, config, projectRoot, depth + 1); if (!nested.allowed) return nested; } } catch { return { allowed: false, ruleId: "shell.obfuscated-interpreter" }; }
+	try {
+		for (const body of bashSubstitutions(command)) {
+			const nested = evaluateBash(body, cwd, config, projectRoot, depth + 1);
+			if (nested.ruleId === "shell.unsupported-interpreter") unsupported = true;
+			else if (!nested.allowed) return nested;
+		}
+	} catch { return { allowed: false, ruleId: "shell.obfuscated-interpreter" }; }
 	if (/^\s*:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:\s*$/.test(command)) return { allowed: false, ruleId: "shell.destructive-root" };
 	let parsed;
 	try { parsed = lex(command); } catch { return { allowed: false, ruleId: "shell.obfuscated-interpreter" }; }
@@ -834,10 +885,16 @@ function evaluateBash(command, cwd, config = AGENT_CONFIGS.claude, projectRoot =
 		if (/^(?:powershell|pwsh)(?:\.exe)?$/i.test(executable) && tokens.some((token) => /^-(?:enc|encodedcommand)$/i.test(token))) return { allowed: false, ruleId: "shell.obfuscated-interpreter" };
 		if (/^(?:bash|sh|zsh|dash|ksh)$/.test(executable)) {
 			const flag = tokens.findIndex((token) => /^-[^-]*c[^-]*$/.test(token));
-			if (flag >= 0) { const body = tokens[flag + 1]; if (!body || /\$(?!\()/.test(body)) return { allowed: false, ruleId: "shell.obfuscated-interpreter" }; const nested = evaluateBash(body, cwd, config, projectRoot, depth + 1); if (!nested.allowed) return nested; }
+			if (flag >= 0) {
+				const body = tokens[flag + 1];
+				if (!body || /\$(?!\()/.test(body)) return { allowed: false, ruleId: "shell.obfuscated-interpreter" };
+				const nested = evaluateBash(body, cwd, config, projectRoot, depth + 1);
+				if (nested.ruleId === "shell.unsupported-interpreter") unsupported = true;
+				else if (!nested.allowed) return nested;
+			}
 		}
 	}
-	return { allowed: true };
+	return unsupported ? { allowed: false, ruleId: "shell.unsupported-interpreter" } : { allowed: true };
 }
 function evaluatePowerShell(command, cwd, config = AGENT_CONFIGS.claude, projectRoot = PROJECT_ROOT) {
 	const parsed = lex(command, true);
@@ -939,6 +996,7 @@ function diagnostic(error) {
 }
 function denialDiagnostic(toolName, decision) {
 	const tool = SUPPORTED_TOOLS.includes(toolName) ? toolName : "supported tool";
+	if (decision.ruleId === "shell.unsupported-interpreter") return "javi-forge PreToolUse denied Bash [shell.unsupported-interpreter]: quoted Python heredoc execution is unsupported";
 	if (decision.ambiguity) return `javi-forge PreToolUse denied ${tool} [${decision.ruleId}]: ${decision.ambiguity.utility} ${decision.ambiguity.profile} ${decision.ambiguity.sink} semantics denied as ambiguous`;
 	return `javi-forge PreToolUse denied ${tool} [${decision.ruleId}]: global guard policy denied the invocation`;
 }

package/assets/claude-hooks/javi-forge-windows-secure-object.ps1

@@ -92,6 +92,7 @@ namespace JaviForge
         private const uint WRITE_OWNER_A = 0x00080000;
         private const uint DELETE_A = 0x00010000;
         private const uint FILE_READ_ATTRIBUTES = 0x0080;
+        private const uint DIRECTORY_FLUSH_ACCESS = GENERIC_WRITE | READ_CONTROL | FILE_READ_ATTRIBUTES;
 
         private const uint FILE_SHARE_READ = 0x1;
         private const uint FILE_SHARE_WRITE = 0x2;
@@ -866,12 +867,34 @@ namespace JaviForge
                 // No opaque re-check here (unlike unlink/rmdir): both endpoints are our
                 // own just-created nodes under the held parent-chain lock, so no on-path
                 // node can be swapped while the chain handle is held.
-                if (!MoveFileExW(fromFull, toFull,
-                    MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH))
-                    return OpResult.Fail(R_CHAIN, "rename failed " + Marshal.GetLastWin32Error()
-                        + " " + fromFull);
-                FlushFileBuffers(dir.Handle);
-                return OpResult.Good();
+                int flushErr;
+                IntPtr flushHandle = OpenNoFollow(dir.Path, DIRECTORY_FLUSH_ACCESS,
+                    FILE_SHARE_READ | FILE_SHARE_WRITE, out flushErr);
+                if (flushHandle == INVALID_HANDLE)
+                    return OpResult.Fail(R_CHAIN, "rename flush-open failed " + flushErr + " " + dir.Path);
+                try
+                {
+                    uint attr; string opaque; bool zeroId;
+                    if (!ReadInfo(flushHandle, out attr, out opaque, out zeroId))
+                        return OpResult.Fail(R_CHAIN, "rename flush-open info failed " + dir.Path);
+                    if ((attr & FILE_ATTRIBUTE_REPARSE_POINT) != 0)
+                        return OpResult.Fail(R_CHAIN, "rename flush-open reparse point " + dir.Path);
+                    if ((attr & FILE_ATTRIBUTE_DIRECTORY) == 0)
+                        return OpResult.Fail(R_CHAIN, "rename flush-open not a directory " + dir.Path);
+                    if (zeroId)
+                        return OpResult.Fail(R_CHAIN, "rename flush-open unresolvable identity " + dir.Path);
+                    if (!String.Equals(opaque, dir.Opaque, StringComparison.OrdinalIgnoreCase))
+                        return OpResult.Fail(R_CHAIN, "rename flush-open identity changed " + dir.Path);
+                    if (!MoveFileExW(fromFull, toFull,
+                        MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH))
+                        return OpResult.Fail(R_CHAIN, "rename failed " + Marshal.GetLastWin32Error()
+                            + " " + fromFull);
+                    if (!FlushFileBuffers(flushHandle))
+                        return OpResult.Fail(R_CHAIN, "rename flush failed " + Marshal.GetLastWin32Error()
+                            + " " + dir.Path);
+                    return OpResult.Good();
+                }
+                finally { CloseHandle(flushHandle); }
             }
             catch (Exception ex) { return OpResult.Fail(R_CHAIN, "rename exception " + ex.Message); }
         }

package/assets/claude-hooks/manifest.json

@@ -4,7 +4,7 @@
 		"name": "javi-forge-skillguard-pre-tool-use.mjs",
 		"version": 1,
 		"policyVersion": 2,
-		"sha256": "6edfbb31ce0551b27e38ae1ffd1daf9cc4bea54f2c86687c5124132af5b8c0af",
+		"sha256": "507a57a15f1b967103bb1eefe701a74813d5a9603fa7bcc15579a215b03621e3",
 		"historical": [
 			"78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc",
 			"5dc2a5c31131f4ac7d8657c78b950de52776aad6eaefe78ea0d764a9963c4425",
@@ -12,7 +12,8 @@
 			"3581862f0567cce75a58b693c9ade80d39ee7d58add11537a34a8461c47c1ed4",
 			"54a270f28b068450b79547a88ec6f2d4854514392fd5f38ed1d6174ea093d7aa",
 			"9a565cec31d9e091e3fb9420b86685f824733bc1ebe479f086b2b955aba6ef3e",
-			"59fc4224975ad64cfc85bab50ec60d9bd4948070e9d41f42ab43e6d8231c19a1"
+			"59fc4224975ad64cfc85bab50ec60d9bd4948070e9d41f42ab43e6d8231c19a1",
+			"6edfbb31ce0551b27e38ae1ffd1daf9cc4bea54f2c86687c5124132af5b8c0af"
 		]
 	},
 	"settingsEntries": {
@@ -30,7 +31,7 @@
 	"installerHelpers": {
 		"windowsSecureObject": {
 			"name": "javi-forge-windows-secure-object.ps1",
-			"sha256": "2289ef6ac6b039ec74dc3ea0894413e243ff9bea963f04008a356b3838f9b8dd"
+			"sha256": "4ee446d4e540adbea88c343df540efdcad1a5b26d31481ac5ae7057d8375cd11"
 		}
 	}
 }

package/assets/preparation-worker.c

@@ -0,0 +1,180 @@
+/* Fixed Linux x86-64 data-only preparation worker. Build statically; never run
+ * generated helpers. Operator approves the exact binary AND this source digest.
+ * JSON checks are artifact validation, not helper behavior or domain-schema tests. */
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <linux/audit.h>
+#include <linux/filter.h>
+#include <linux/seccomp.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/prctl.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/syscall.h>
+#include <time.h>
+#include <unistd.h>
+
+#define LIMIT 1048576
+#define DIR_FLAGS (O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC)
+#define FILE_FLAGS (O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC)
+static const char *names[6] = {"app-request.json", "minimal.py", "test_minimal.py", "dispatch.py", "run_gateway.py", "preparation-result.json"};
+static unsigned char *data[6];
+static size_t sizes[6];
+extern char **environ;
+
+#define ALLOW(n) BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, __NR_##n, 0, 1), BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW)
+static int restrict_syscalls(void) {
+    struct sock_filter rules[] = {
+        BPF_STMT(BPF_LD | BPF_W | BPF_ABS, offsetof(struct seccomp_data, arch)),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, AUDIT_ARCH_X86_64, 1, 0),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS),
+        BPF_STMT(BPF_LD | BPF_W | BPF_ABS, offsetof(struct seccomp_data, nr)),
+        ALLOW(read), ALLOW(write), ALLOW(close), ALLOW(fstat), ALLOW(newfstatat),
+        ALLOW(fsync), ALLOW(fchmod), ALLOW(mkdirat), ALLOW(unlinkat),
+        ALLOW(brk), ALLOW(mmap), ALLOW(munmap), ALLOW(mprotect), ALLOW(futex),
+        ALLOW(clock_gettime), ALLOW(alarm), ALLOW(rt_sigaction), ALLOW(rt_sigprocmask),
+        ALLOW(rt_sigreturn), ALLOW(exit), ALLOW(exit_group), ALLOW(getpid),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, __NR_openat, 1, 0),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ERRNO | EPERM),
+        BPF_STMT(BPF_LD | BPF_W | BPF_ABS, offsetof(struct seccomp_data, args[2])),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, DIR_FLAGS, 2, 0),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, FILE_FLAGS, 1, 0),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ERRNO | EPERM),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW)
+    };
+    struct sock_fprog program = {(unsigned short)(sizeof(rules) / sizeof(rules[0])), rules};
+    return prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) || prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, &program);
+}
+static int isolation_probes(int parent) {
+    errno = 0;
+    if (syscall(__NR_socket, AF_INET, SOCK_STREAM, 0) != -1 || errno != EPERM) return 0;
+    errno = 0;
+    if (openat(parent, "credential-probe", O_RDONLY) != -1 || errno != EPERM) return 0;
+    errno = 0;
+    if (syscall(__NR_clone, 0, 0, 0, 0, 0) != -1 || errno != EPERM) return 0;
+    errno = 0;
+    if (syscall(__NR_execve, "/worker", 0, 0) != -1 || errno != EPERM) return 0;
+    return 1;
+}
+
+struct json { const unsigned char *p, *end; };
+static void ws(struct json *j) { while (j->p < j->end && (*j->p == ' ' || *j->p == '\n' || *j->p == '\r' || *j->p == '\t')) j->p++; }
+static int hex(unsigned char c) { return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'); }
+static int string(struct json *j) {
+    if (j->p == j->end || *j->p++ != '"') return 0;
+    while (j->p < j->end) {
+        unsigned char c = *j->p++;
+        if (c == '"') return 1;
+        if (c < 32) return 0;
+        if (c == '\\') {
+            if (j->p == j->end) return 0;
+            c = *j->p++;
+            if (c == 'u') {
+                for (int i = 0; i < 4; i++) if (j->p == j->end || !hex(*j->p++)) return 0;
+            } else if (!strchr("\"\\/bfnrt", c)) return 0;
+        } else if (c >= 128) {
+            unsigned int value; int count;
+            if (c >= 0xc2 && c <= 0xdf) { value = c & 31; count = 1; }
+            else if (c >= 0xe0 && c <= 0xef) { value = c & 15; count = 2; }
+            else if (c >= 0xf0 && c <= 0xf4) { value = c & 7; count = 3; }
+            else return 0;
+            int remaining = count;
+            while (remaining--) { if (j->p == j->end || (*j->p & 0xc0) != 0x80) return 0; value = (value << 6) | (*j->p++ & 63); }
+            if ((count == 2 && value < 0x800) || (count == 3 && value < 0x10000) || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff)) return 0;
+        }
+    }
+    return 0;
+}
+static int value(struct json *j, int depth) {
+    ws(j); if (depth > 64 || j->p == j->end) return 0;
+    unsigned char c = *j->p;
+    if (c == '"') return string(j);
+    if (c == '{' || c == '[') {
+        unsigned char stop = c == '{' ? '}' : ']'; j->p++; ws(j);
+        if (j->p < j->end && *j->p == stop) { j->p++; return 1; }
+        for (;;) {
+            if (c == '{') { if (!string(j)) return 0; ws(j); if (j->p == j->end || *j->p++ != ':') return 0; }
+            if (!value(j, depth + 1)) return 0;
+            ws(j); if (j->p == j->end) return 0;
+            unsigned char next = *j->p++; if (next == stop) return 1;
+            if (next != ',') return 0;
+            ws(j);
+        }
+    }
+    const char *literal = c == 't' ? "true" : c == 'f' ? "false" : c == 'n' ? "null" : NULL;
+    if (literal) { size_t n = strlen(literal); if ((size_t)(j->end - j->p) < n || memcmp(j->p, literal, n)) return 0; j->p += n; return 1; }
+    if (*j->p == '-') j->p++;
+    if (j->p == j->end) return 0;
+    if (*j->p == '0') j->p++;
+    else { if (*j->p < '1' || *j->p > '9') return 0; do { j->p++; } while (j->p < j->end && *j->p >= '0' && *j->p <= '9'); }
+    if (j->p < j->end && *j->p == '.') { j->p++; const unsigned char *start = j->p; while (j->p < j->end && *j->p >= '0' && *j->p <= '9') j->p++; if (j->p == start) return 0; }
+    if (j->p < j->end && (*j->p == 'e' || *j->p == 'E')) { j->p++; if (j->p < j->end && (*j->p == '+' || *j->p == '-')) j->p++; const unsigned char *start = j->p; while (j->p < j->end && *j->p >= '0' && *j->p <= '9') j->p++; if (j->p == start) return 0; }
+    return 1;
+}
+static int object(const unsigned char *bytes, size_t n) { struct json j = {bytes, bytes + n}; ws(&j); if (j.p == j.end || *j.p != '{' || !value(&j, 0)) return 0; ws(&j); return j.p == j.end; }
+static int write_all(int fd, const unsigned char *bytes, size_t length) {
+    while (length) { ssize_t n = write(fd, bytes, length); if (n <= 0) return 0; bytes += n; length -= (size_t)n; } return 1;
+}
+
+int main(int argc, char **argv) {
+    (void)argv;
+    alarm(30); umask(077); setvbuf(stdout, NULL, _IONBF, 0);
+    if (argc != 1) return 11;
+    if (environ && *environ && (environ[1] || strcmp(environ[0], "PWD=/"))) return 12;
+    if (clearenv()) return 13;
+    struct timespec started; if (clock_gettime(CLOCK_MONOTONIC, &started)) return 10;
+    int parent = open("/out", DIR_FLAGS); struct stat parent_stat, existing;
+    if (parent < 0 || fstat(parent, &parent_stat) || (parent_stat.st_mode & 0777) != 0700) return 10;
+    if (fstatat(parent, "attempt-3", &existing, AT_SYMLINK_NOFOLLOW) == 0 || errno != ENOENT) return 10;
+    unsigned long long dev, ino; FILE *identity = fopen("/identity", "r");
+    if (!identity || fscanf(identity, "%llu %llu", &dev, &ino) != 2 || dev != (unsigned long long)parent_stat.st_dev || ino != (unsigned long long)parent_stat.st_ino) return 10;
+    fclose(identity);
+    size_t total = 0;
+    for (int i = 0; i < 6; i++) {
+        char filename[128]; snprintf(filename, sizeof(filename), "/payload/%s", names[i]);
+        int fd = open(filename, O_RDONLY | O_NOFOLLOW | O_CLOEXEC); struct stat st;
+        if (fd < 0 || fstat(fd, &st) || !S_ISREG(st.st_mode) || st.st_size < 0 || st.st_size > LIMIT) return 10;
+        sizes[i] = (size_t)st.st_size; total += sizes[i]; if (total > LIMIT) return 10;
+        data[i] = malloc(sizes[i] + 1); if (!data[i]) return 10;
+        size_t offset = 0;
+        while (offset < sizes[i]) { ssize_t n = read(fd, data[i] + offset, sizes[i] - offset); if (n <= 0) return 10; offset += (size_t)n; }
+        close(fd); data[i][sizes[i]] = 0;
+    }
+    if (restrict_syscalls() || !isolation_probes(parent)) return 10;
+#ifdef PREPARATION_FIXTURE_NOT_READY
+    for (;;) { /* Test-only readiness stall, never a production build. */ }
+#endif
+    puts("READY");
+    char go; if (read(STDIN_FILENO, &go, 1) != 1 || go != 'G') return 10;
+    alarm(10);
+#ifdef PREPARATION_FIXTURE_STALL
+    for (;;) { /* Test-only compiled variant, approved only by fixture keys. */ }
+#endif
+    if (!object(data[0], sizes[0]) || !object(data[5], sizes[5])) return 20;
+    for (int i = 1; i < 5; i++) if (!sizes[i] || memchr(data[i], 0, sizes[i])) return 20;
+    puts("VALID");
+    struct timespec now; if (clock_gettime(CLOCK_MONOTONIC, &now)) return 20;
+    long elapsed = now.tv_sec - started.tv_sec; if (elapsed >= 30) return 20;
+    alarm((unsigned int)(30 - elapsed));
+    if (mkdirat(parent, "attempt-3", 0700)) return 30;
+    int dir = openat(parent, "attempt-3", DIR_FLAGS); struct stat directory_stat;
+    if (dir < 0 || fstat(dir, &directory_stat)) return 30;
+    printf("DIR %llu %llu\n", (unsigned long long)directory_stat.st_dev, (unsigned long long)directory_stat.st_ino);
+    for (int i = 0; i < 6; i++) {
+        int fd = openat(dir, names[i], FILE_FLAGS, 0600); struct stat st;
+        if (fd < 0 || fstat(fd, &st)) return 30;
+        printf("FILE %d %llu %llu\n", i, (unsigned long long)st.st_dev, (unsigned long long)st.st_ino);
+        if (fchmod(fd, 0600) || !write_all(fd, data[i], sizes[i]) || fsync(fd)) return 30;
+        close(fd);
+#ifdef PREPARATION_FIXTURE_PARTIAL
+        if (i == 0) return 30;
+#endif
+    }
+    if (fsync(dir) || fsync(parent)) return 30;
+    close(dir); close(parent); puts("DONE"); return 0;
+}

package/dist/cli/dispatch/doctor.d.ts

@@ -0,0 +1,3 @@
+import { type DoctorOptions } from "../../commands/doctor.js";
+export default function DoctorController({ dryRun, refreshContext, }: DoctorOptions): import("react").FunctionComponentElement<import("../../ui/Doctor.js").DoctorProps>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/dispatch/doctor.js

@@ -0,0 +1,27 @@
+import { createElement, useEffect, useState } from "react";
+import { runDoctor } from "../../commands/doctor.js";
+import Doctor from "../../ui/Doctor.js";
+export default function DoctorController({ dryRun = false, refreshContext = false, }) {
+    const [result, setResult] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const runCheck = () => {
+        setLoading(true);
+        setResult(null);
+        setError(null);
+        void runDoctor(undefined, { dryRun, refreshContext })
+            .then((nextResult) => {
+            setResult(nextResult);
+            setLoading(false);
+        })
+            .catch((nextError) => {
+            setError(String(nextError));
+            setLoading(false);
+        });
+    };
+    useEffect(() => {
+        runCheck();
+    }, [dryRun, refreshContext]);
+    return createElement(Doctor, { loading, result, error, onRerun: runCheck });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/dispatch/simple-renderers.d.ts

@@ -15,7 +15,7 @@ export interface RendererDeps {
     error?: (message: string) => void;
     setExitCode?: (code: number) => void;
 }
-export declare function handleDoctor(_cli: CLI, ctx: RendererCtx, deps?: RendererDeps): void;
+export declare function handleDoctor(cli: CLI, ctx: RendererCtx, deps?: RendererDeps): void;
 export declare function handleAnalyze(cli: CLI, ctx: RendererCtx): void;
 export declare function handleLlmsTxt(cli: CLI, ctx: RendererCtx): void;
 export declare function handlePlugin(cli: CLI, ctx: RendererCtx): void;

package/dist/cli/dispatch/simple-renderers.js

@@ -13,11 +13,11 @@ import { resolvePlatformSupport } from "../../lib/platform-support.js";
 import AnalyzeUI from "../../ui/AnalyzeUI.js";
 import App from "../../ui/App.js";
 import { CIProvider as CIContextProvider } from "../../ui/CIContext.js";
-import Doctor from "../../ui/Doctor.js";
 import LlmsTxt from "../../ui/LlmsTxt.js";
 import Plugin from "../../ui/Plugin.js";
 import { VALID_CI, VALID_MEMORY, VALID_STACKS } from "../validators.js";
-export function handleDoctor(_cli, ctx, deps = {}) {
+import DoctorController from "./doctor.js";
+export function handleDoctor(cli, ctx, deps = {}) {
     const platformSupport = resolvePlatformSupport(deps.platform ?? process.platform);
     if (platformSupport) {
         (deps.error ?? console.error)(`${platformSupport.refusalCode}: ${platformSupport.guidance}`);
@@ -28,7 +28,7 @@ export function handleDoctor(_cli, ctx, deps = {}) {
         return;
     }
     (deps.render ?? render)(React.createElement(CIContextProvider, { isCI: ctx.isCI },
-        React.createElement(Doctor, null)), { stdin: ctx.inkStdin });
+        React.createElement(DoctorController, { dryRun: cli.flags.dryRun === true, refreshContext: cli.flags.refreshContext === true })), { stdin: ctx.inkStdin });
 }
 export function handleAnalyze(cli, ctx) {
     render(React.createElement(CIContextProvider, { isCI: ctx.isCI },

package/dist/cli/help.d.ts

@@ -8,7 +8,7 @@
  * Help banner shown by meow when `--help` is passed or invalid args are supplied.
  * Multi-line template literal — preserve exact formatting (whitespace is significant).
  */
-export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Enable the TDD pre-commit section + install managed hooks\n    tdd pipeline      Enable the TDD pre-push section (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  SkillGuard install gate (plugin add / plugin import / skills auto)\n    Every install is scanned before anything is written. Refusals are\n    fail-closed and name the offending files:\n    - SKILL.md files that block (critical threats) are refused \u2014 always.\n    - Unscannable files (binary, oversized, unreadable) are refused unless\n      --force is given.\n    - Symlinks anywhere in the tree and SKILL.md files outside the declared\n      set are manifest-integrity refusals \u2014 they are refused even with --force.\n    - Empty or missing skills.json `skills` array on import is refused.\n    A refused install/auto-install exits non-zero (exit 1) so scripts and CI\n    can tell a refusal apart from success; clean installs \u2014 including\n    --force-lifted unscannable ones \u2014 exit 0.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge plugin add org/repo\n    $ javi-forge plugin add org/repo --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
+export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Enable the TDD pre-commit section + install managed hooks\n    tdd pipeline      Enable the TDD pre-push section (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --refresh-context  Refresh .context/ during doctor (writes INDEX.md, summary.md, manifest timestamp)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  SkillGuard install gate (plugin add / plugin import / skills auto)\n    Every install is scanned before anything is written. Refusals are\n    fail-closed and name the offending files:\n    - SKILL.md files that block (critical threats) are refused \u2014 always.\n    - Unscannable files (binary, oversized, unreadable) are refused unless\n      --force is given.\n    - Symlinks anywhere in the tree and SKILL.md files outside the declared\n      set are manifest-integrity refusals \u2014 they are refused even with --force.\n    - Empty or missing skills.json `skills` array on import is refused.\n    A refused install/auto-install exits non-zero (exit 1) so scripts and CI\n    can tell a refusal apart from success; clean installs \u2014 including\n    --force-lifted unscannable ones \u2014 exit 0.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge plugin add org/repo\n    $ javi-forge plugin add org/repo --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
 /**
  * Per-command help for `ci`, shown by `javi-forge ci --help` (or when `ci` is
  * given an unknown subcommand). Kept consistent with the global HELP_TEXT
@@ -30,6 +30,10 @@ export declare const FLAGS_SCHEMA: {
         readonly type: "boolean";
         readonly default: false;
     };
+    readonly refreshContext: {
+        readonly type: "boolean";
+        readonly default: false;
+    };
     readonly stack: {
         readonly type: "string";
         readonly default: "";

package/dist/cli/help.js

@@ -59,6 +59,7 @@ export const HELP_TEXT = `
     --mock          Enable mock-first mode (no real API keys needed)
     --local-ai      Include local AI dev stack (Ollama + Docker Compose)
     --batch         Non-interactive mode (auto-proceed, no keyboard input)
+    --refresh-context  Refresh .context/ during doctor (writes INDEX.md, summary.md, manifest timestamp)
     --deep          Enable deep analysis (conflict + duplicate detection)
     --budget, -b    Token budget limit for skills (default: 8000)
     --skills-dir    Custom skills directory path
@@ -214,6 +215,7 @@ export const FLAGS_SCHEMA = {
     // `ci --help` can show ci-specific usage instead of the global banner).
     help: { type: "boolean", shortFlag: "h", default: false },
     dryRun: { type: "boolean", default: false },
+    refreshContext: { type: "boolean", default: false },
     stack: { type: "string", default: "" },
     ci: { type: "string", default: "" },
     memory: { type: "string", default: "" },

package/dist/cli/main.js

@@ -10,11 +10,21 @@ import { handleTdd } from "./dispatch/tdd.js";
 import { handleWorkflow } from "./dispatch/workflow.js";
 import { FLAGS_SCHEMA, HELP_TEXT } from "./help.js";
 import { createInkStdin, detectCI, setupUpdateNotifier } from "./runtime.js";
+const KNOWN_COMMANDS = new Set([
+    "init",
+    "tdd",
+    "ci",
+    "hooks",
+    "doctor",
+    "analyze",
+    "workflow",
+    "llms-txt",
+    "plugin",
+    "skills",
+    "skill",
+    "security",
+]);
 export async function runCli() {
-    // Check for updates in background (non-blocking, cached 24h)
-    const _require = createRequire(import.meta.url);
-    const pkg = _require("../../package.json");
-    setupUpdateNotifier(pkg);
     const cli = meow(HELP_TEXT, {
         importMeta: import.meta,
         flags: FLAGS_SCHEMA,
@@ -23,12 +33,23 @@ export async function runCli() {
         autoHelp: false,
     });
     const subcommand = cli.input[0] ?? "init";
+    if (!KNOWN_COMMANDS.has(subcommand)) {
+        console.error(`Unknown command "${subcommand}". Run javi-forge --help for usage.`);
+        process.exit(1);
+    }
     // Global --help: every command except `ci` and `hooks` shows the global banner
     // here. Those two own their per-command help inside their handlers.
     if (cli.flags.help && subcommand !== "ci" && subcommand !== "hooks") {
         console.log(HELP_TEXT);
         process.exit(0);
     }
+    // Check for updates in background (non-blocking, cached 24h). Diagnostics and
+    // dry-runs must not create notifier cache/state before doing their actual work.
+    if (subcommand !== "doctor" && !cli.flags.dryRun) {
+        const _require = createRequire(import.meta.url);
+        const pkg = _require("../../package.json");
+        setupUpdateNotifier(pkg);
+    }
     const isCI = detectCI(cli.flags);
     const inkStdin = createInkStdin();
     switch (subcommand) {
@@ -76,7 +97,7 @@ export async function runCli() {
             await handleSecurity(cli);
             break;
         }
-        default: {
+        case "init": {
             handleInitDefault(cli, { inkStdin, isCI });
             break;
         }

package/dist/commands/doctor.d.ts

@@ -1,12 +1,16 @@
 import fs from "fs-extra";
 import { detectStack } from "../lib/common.js";
-import { refreshContextDir } from "../lib/context.js";
+import { detectDependenciesDetailed, refreshContextDir } from "../lib/context.js";
 import { execFileAsync } from "../lib/exec.js";
 import { listInstalledPlugins } from "../lib/plugin.js";
 import type { DoctorResult } from "../types/index.js";
 export type CheckStatus = "ok" | "fail" | "skip";
 type DoctorFilesystem = Pick<typeof fs, "pathExists" | "readJson" | "readdir">;
-export interface DoctorDeps {
+export interface DoctorOptions {
+    dryRun?: boolean;
+    refreshContext?: boolean;
+}
+export interface DoctorDeps extends DoctorOptions {
     platform?: string;
     cwd?: () => string;
     filesystem?: DoctorFilesystem;
@@ -14,6 +18,7 @@ export interface DoctorDeps {
     stackDetector?: typeof detectStack;
     pluginLister?: typeof listInstalledPlugins;
     contextRefresher?: typeof refreshContextDir;
+    dependencyDetector?: typeof detectDependenciesDetailed;
 }
 interface RemoteInfo {
     host: "github" | "gitlab" | "other";