arkgate 2.12.0 → 3.0.0

package/bin/lib/write-path-detect.mjs

@@ -1,118 +1,63 @@
 /**
- * W5 — Write-path capability surface for doctor (stable additive JSON).
- * Extracted from agent-gates so install orchestration stays scannable.
+ * Active-host write-path capability surface for doctor and install checks.
  *
- * Detects whether installed agent gates expose:
- *   - MCP prepare-write / validate_code (autoPatch) tools
- *   - PreToolUse hook in reject-only vs repair mode (--hook-repair / ARK_HOOK_REPAIR)
- *
- * Never claims silent apply; "repair" means host can re-inject a patch after hard deny.
+ * `inventory` records every supported host found in the repository. Top-level
+ * capabilities and compatibility fields describe only `activeHost`, so a
+ * Claude/Grok hook can never become a Codex/Cursor guarantee.
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
+import { formatHostSupportSummary } from './host-support-matrix.mjs';
+import { buildWritePathCapabilityModel } from './write-path-capabilities.mjs';
 
-/**
- * @returns {{
- *   mode: 'repair' | 'reject-only' | 'mcp-only' | 'none',
- *   prepareWrite: boolean,
- *   autoPatch: boolean,
- *   hookPresent: boolean,
- *   hookRepair: boolean,
- *   mcpPresent: boolean,
- *   evidence: string[],
- *   gap: null | { id: string, severity: string, message: string, fix: string },
- * }}
- */
-export function detectWritePathCapabilities(root) {
-  const evidence = [];
-  let hookPresent = false;
-  let hookRepair = false;
-
-  const hookFiles = [
-    '.claude/settings.json',
-    '.grok/hooks/ark-write-gate.json',
-  ];
-  for (const rel of hookFiles) {
-    const abs = path.join(root, rel);
-    if (!fs.existsSync(abs)) continue;
-    let text = '';
-    try {
-      text = fs.readFileSync(abs, 'utf8');
-    } catch {
-      continue;
-    }
-    // PreToolUse / write-gate command referencing ark(-gate)?-mcp --hook
-    if (
-      /--hook\b/.test(text) ||
-      /\b(ark|arkgate)-mcp\b[\s\S]{0,80}--hook\b/.test(text) ||
-      /\b--hook\b[\s\S]{0,80}\b(ark|arkgate)-mcp\b/.test(text)
-    ) {
-      hookPresent = true;
-      evidence.push(rel);
-    }
-    if (
-      /--hook-repair\b/.test(text) ||
-      /ARK_HOOK_REPAIR\s*=\s*['"]?(1|true|yes|on)/i.test(text)
-    ) {
-      hookRepair = true;
-      if (!evidence.includes(rel)) evidence.push(rel);
-    }
-  }
-
-  let mcpPresent = false;
-  const mcpFiles = ['.mcp.json', '.cursor/mcp.json', '.grok/config.toml'];
-  for (const rel of mcpFiles) {
-    const abs = path.join(root, rel);
-    if (!fs.existsSync(abs)) continue;
-    let text = '';
-    try {
-      text = fs.readFileSync(abs, 'utf8');
-    } catch {
-      continue;
-    }
-    if (
-      /\b(ark|arkgate)-mcp\b/.test(text) ||
-      /mcp_servers\.ark\b/.test(text) ||
-      /"ark"\s*:\s*\{/.test(text) ||
-      /mcpServers[\s\S]*\bark\b/.test(text)
-    ) {
-      mcpPresent = true;
-      evidence.push(rel);
-    }
-  }
+function installToolsForHost(activeHost) {
+  return activeHost === 'unknown'
+    ? 'claude,grok,cursor,codex'
+    : activeHost;
+}
 
-  // Package tools when MCP is wired: ark_prepare_write + validate_code(autoPatch).
-  // Hook repair emits machine-readable autoPatch without silent write.
-  const prepareWrite = mcpPresent;
-  const autoPatch = mcpPresent || hookRepair;
+export function detectWritePathCapabilities(root, explicitHost) {
+  const model = buildWritePathCapabilityModel(root, explicitHost);
+  const { activeHost, support, capabilities, capabilityEvidence, inventory } = model;
+  const hardWrite = capabilities['hard-write'];
+  const advisoryWrite = capabilities['advisory-write'];
+  const repairPayload = capabilities['repair-payload'];
 
   /** @type {'repair' | 'reject-only' | 'mcp-only' | 'none'} */
   let mode = 'none';
-  if (hookPresent && hookRepair) mode = 'repair';
-  else if (hookPresent && !hookRepair) mode = 'reject-only';
-  else if (mcpPresent) mode = 'mcp-only';
+  if (hardWrite && repairPayload) mode = 'repair';
+  else if (hardWrite) mode = 'reject-only';
+  else if (advisoryWrite) mode = 'mcp-only';
 
+  const tools = installToolsForHost(activeHost);
   let gap = null;
   if (mode === 'none') {
     gap = {
       id: 'write-path-none',
       severity: 'warn',
       message:
-        'Write path is not installed — no PreToolUse hook and no Ark MCP. Agents write without architecture gate or prepare-write.',
-      fix: arkCommand(root, 'ark-check', '--install-agent-gates'),
+        `Active host ${activeHost} has no hard write boundary or advisory Ark MCP. ` +
+        (capabilities['merge-gate']
+          ? 'The CI check remains separate and does not block local writes.'
+          : 'No Ark CI check was detected either.'),
+      fix: arkCommand(
+        root,
+        'ark-check',
+        `--install-agent-gates --tools ${tools}`
+      ),
     };
   } else if (mode === 'reject-only') {
     gap = {
       id: 'write-path-reject-only',
       severity: 'info',
-      message: mcpPresent
-        ? 'PreToolUse hook is reject-only (hard block, no ARK_REPAIR_JSON). MCP still exposes prepare-write/autoPatch — enable --hook-repair so the write boundary itself can re-inject patches.'
-        : 'Write path is reject-only (hard block with prose; no repair payload). Enable --hook-repair or ARK_HOOK_REPAIR=1 so hosts can re-inject patches without full re-draft.',
+      message:
+        `Active host ${activeHost} has a hard write boundary without a repair payload. ` +
+        (advisoryWrite
+          ? 'Advisory MCP tools remain available.'
+          : 'Install its MCP surface or enable hook repair for guided re-entry.'),
       fix: arkCommand(
         root,
         'ark-check',
-        '--install-agent-gates --tools claude,grok --force'
+        `--install-agent-gates --tools ${tools} --force`
       ),
     };
   } else if (mode === 'mcp-only') {
@@ -120,19 +65,37 @@ export function detectWritePathCapabilities(root) {
       id: 'write-path-mcp-only',
       severity: 'info',
       message:
-        'MCP exposes prepare-write / autoPatch tools, but no PreToolUse write hook is installed — enforcement is advisory unless the agent calls tools.',
-      fix: arkCommand(root, 'ark-check', '--install-agent-gates --tools claude,grok'),
+        `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
+        'but no hard write boundary; the CI check can still reject the change before merge.',
+      fix: arkCommand(
+        root,
+        'ark-check',
+        `--install-agent-gates --tools ${tools}`
+      ),
     };
   }
 
   return {
+    activeHost,
+    support,
+    supportSummary: formatHostSupportSummary(support),
+    capabilities,
+    capabilityEvidence,
+    inventory,
+    // Compatibility projection for existing doctor/API consumers.
     mode,
-    prepareWrite,
-    autoPatch,
-    hookPresent,
-    hookRepair,
-    mcpPresent,
-    evidence: [...new Set(evidence)],
+    prepareWrite: advisoryWrite,
+    autoPatch: advisoryWrite || repairPayload,
+    hookPresent: hardWrite,
+    hookRepair: repairPayload,
+    mcpPresent: advisoryWrite,
+    evidence: [
+      ...new Set([
+        ...capabilityEvidence['hard-write'],
+        ...capabilityEvidence['advisory-write'],
+        ...capabilityEvidence['repair-payload'],
+      ]),
+    ],
     gap,
   };
 }

package/compat/nestjs.cjs

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('@arkgate/runtime/nestjs');

package/compat/nestjs.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Install `@arkgate/runtime` and import from `@arkgate/runtime/nestjs`. */
+export * from '@arkgate/runtime/nestjs';

package/compat/nestjs.js

@@ -0,0 +1 @@
+export * from '@arkgate/runtime/nestjs';

package/compat/runtime.cjs

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('@arkgate/runtime');

package/compat/runtime.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Install and import from `@arkgate/runtime`. This shim is removed in ArkGate 4. */
+export * from '@arkgate/runtime';

package/compat/runtime.js

@@ -0,0 +1 @@
+export * from '@arkgate/runtime';

package/dist/configContract-BxSIwVRo.d.cts

@@ -0,0 +1,259 @@
+/**
+ * Canonical, pure contract for ark.config.json.
+ *
+ * Tooling adapters own filesystem I/O; this module owns JSON parsing, deterministic
+ * migration, defaults, validation, diagnostics, and the published JSON Schema.
+ * The standalone CLI artifact is generated into bin/lib/config-contract.mjs.
+ */
+declare const ARK_CONFIG_SCHEMA_VERSION: "1.0";
+type ArkConfigCyclePolicy = 'strict' | 'soft' | 'framework-soft' | 'off';
+type ArkConfigLayer = {
+    name: string;
+    patterns: string[];
+    exclude?: string[];
+    intentPrefixes?: string[];
+    description?: string;
+    forbiddenGlobals?: string[];
+    mayImportInfrastructure?: boolean;
+    optional?: boolean;
+};
+type ArkConfigRule = {
+    from: string;
+    to: string;
+    allowed: boolean;
+    message?: string;
+    peerIsolation?: boolean;
+    sliceFolders?: string[];
+};
+type ArkConfigSafety = {
+    maxTsSuppressions?: number;
+    maxAnyCasts?: number;
+    allowInMemory?: boolean;
+    allowDisabledPeerIsolation?: boolean;
+};
+type ArkConfig = {
+    $schema: string;
+    schemaVersion: typeof ARK_CONFIG_SCHEMA_VERSION;
+    name?: string;
+    include: string[];
+    exclude?: string[];
+    excludeGenerated?: boolean;
+    frameworkOverlay?: string;
+    layers: ArkConfigLayer[];
+    rules: ArkConfigRule[];
+    cyclePolicy?: ArkConfigCyclePolicy;
+    dynamicImportAllowlist?: string[];
+    safety?: ArkConfigSafety;
+};
+declare const ARK_CONFIG_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json";
+    readonly title: "ArkGate architecture contract";
+    readonly description: "Versioned contract consumed identically by ArkGate CLI, MCP, and ESLint surfaces.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["$schema", "schemaVersion", "include", "layers", "rules"];
+    readonly properties: {
+        readonly $schema: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly default: "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json";
+            readonly description: "Editor-facing URL or local path for this JSON Schema.";
+        };
+        readonly schemaVersion: {
+            readonly type: "string";
+            readonly const: "1.0";
+            readonly default: "1.0";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly include: {
+            readonly minItems: 1;
+            readonly default: readonly ["src"];
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly uniqueItems: true;
+        };
+        readonly exclude: {
+            readonly default: readonly [];
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly uniqueItems: true;
+        };
+        readonly excludeGenerated: {
+            readonly type: "boolean";
+            readonly default: true;
+        };
+        readonly frameworkOverlay: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly layers: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly items: {
+                readonly $ref: "#/$defs/layer";
+            };
+        };
+        readonly rules: {
+            readonly type: "array";
+            readonly default: ArkConfigRule[];
+            readonly items: {
+                readonly $ref: "#/$defs/rule";
+            };
+        };
+        readonly cyclePolicy: {
+            readonly type: "string";
+            readonly enum: readonly ["strict", "soft", "framework-soft", "off"];
+            readonly default: "strict";
+        };
+        readonly dynamicImportAllowlist: {
+            readonly default: readonly [];
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly uniqueItems: true;
+        };
+        readonly safety: {
+            readonly $ref: "#/$defs/safety";
+            readonly default: {
+                readonly maxTsSuppressions: 0;
+                readonly maxAnyCasts: 0;
+                readonly allowInMemory: false;
+                readonly allowDisabledPeerIsolation: false;
+            };
+        };
+    };
+    readonly $defs: {
+        readonly layer: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["name", "patterns"];
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly patterns: {
+                    readonly minItems: 1;
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly uniqueItems: true;
+                };
+                readonly exclude: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly uniqueItems: true;
+                };
+                readonly intentPrefixes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly uniqueItems: true;
+                };
+                readonly description: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly forbiddenGlobals: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly uniqueItems: true;
+                };
+                readonly mayImportInfrastructure: {
+                    readonly type: "boolean";
+                };
+                readonly optional: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly rule: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["from", "to", "allowed"];
+            readonly properties: {
+                readonly from: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly to: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly allowed: {
+                    readonly type: "boolean";
+                };
+                readonly message: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly peerIsolation: {
+                    readonly type: "boolean";
+                };
+                readonly sliceFolders: {
+                    readonly minItems: 1;
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly uniqueItems: true;
+                };
+            };
+        };
+        readonly safety: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly maxTsSuppressions: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly default: 0;
+                };
+                readonly maxAnyCasts: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly default: 0;
+                };
+                readonly allowInMemory: {
+                    readonly type: "boolean";
+                    readonly default: false;
+                };
+                readonly allowDisabledPeerIsolation: {
+                    readonly type: "boolean";
+                    readonly default: false;
+                };
+            };
+        };
+    };
+};
+type ArkConfigLoadResult = {
+    config: ArkConfig;
+    migratedFrom: 'unversioned' | null;
+};
+declare function loadArkConfigContract(input: unknown, source?: string): ArkConfigLoadResult;
+declare function parseArkConfigJson(json: string, source?: string): ArkConfigLoadResult;
+
+export { type ArkConfig as A, type ArkConfigRule as a, type ArkConfigLayer as b, type ArkConfigLoadResult as c, ARK_CONFIG_SCHEMA as d, ARK_CONFIG_SCHEMA_VERSION as e, loadArkConfigContract as l, parseArkConfigJson as p };