arkgate 2.13.0 → 3.0.0

package/bin/lib/start-preview.mjs

@@ -0,0 +1,271 @@
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { arkCommand, buildArchitectureRecommendation } from '../ark-shared.mjs';
+import { compactAgentInstructions, instructionRule, mcpJson } from './ci-and-commands.mjs';
+import { claudeSettings, codexHooks, grokHooks, grokProjectConfig } from './hook-templates.mjs';
+
+const COMPACT_HOST_TEMPLATES = {
+  claude: (root) => [
+    ['.claude/settings.json', claudeSettings(root)],
+    ['.mcp.json', mcpJson(root)],
+  ],
+  grok: (root) => [
+    ['.grok/config.toml', grokProjectConfig(root)],
+    ['.grok/hooks/ark-write-gate.json', grokHooks(root)],
+  ],
+  cursor: (root) => [['.cursor/mcp.json', mcpJson(root)]],
+  codex: (root) => [['.codex/hooks.json', codexHooks(root)]],
+  windsurf: (root) => [['.windsurf/rules/ark.md', instructionRule(root)]],
+  cline: (root) => [['.clinerules/ark.md', instructionRule(root)]],
+  copilot: (root) => [['.github/copilot-instructions.md', instructionRule(root)]],
+  kiro: (root) => [['.kiro/steering/ark.md', instructionRule(root)]],
+  roo: (root) => [['.roo/rules/ark.md', instructionRule(root)]],
+  continue: (root) => [['.continue/rules/ark.md', instructionRule(root)]],
+  gemini: (root) => [['GEMINI.md', instructionRule(root)]],
+};
+
+function treeFiles(root) {
+  const files = new Map();
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (['.git', 'node_modules', 'dist', 'coverage'].includes(entry.name)) continue;
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) {
+        files.set(path.relative(root, absolute).split(path.sep).join('/'), fs.readFileSync(absolute));
+      }
+    }
+  };
+  visit(root);
+  return files;
+}
+
+function normalizedContent(content, shadowRoot, root) {
+  if (!content) return content;
+  const text = content.toString('utf8');
+  return text.includes('\u0000') ? content : Buffer.from(text.split(shadowRoot).join(root));
+}
+
+function digest(content) {
+  return `sha256:${crypto.createHash('sha256').update(content ?? Buffer.alloc(0)).digest('hex')}`;
+}
+
+function change(pathname, before, after) {
+  return {
+    path: pathname,
+    action: !before ? 'create' : !after ? 'delete' : 'edit',
+    beforeHash: before ? digest(before) : null,
+    afterHash: after ? digest(after) : null,
+    beforeBase64: before ? before.toString('base64') : null,
+    afterBase64: after ? after.toString('base64') : null,
+  };
+}
+
+function setupBudget(changes) {
+  const generatedChanges = changes.filter((item) => item.path !== 'package.json');
+  const bytes = generatedChanges.reduce(
+    (total, item) => total + (item.afterBase64 ? Buffer.from(item.afterBase64, 'base64').length : 0),
+    0
+  );
+  return {
+    files: generatedChanges.length,
+    bytes,
+    maxFiles: 5,
+    maxBytes: 25 * 1024,
+    ok: generatedChanges.length <= 5 && bytes < 25 * 1024,
+  };
+}
+
+function commands(root, args, helpers) {
+  if (args.removeHost) {
+    return [`ark start --root ${root} --tools ${args.removeHost} --apply`];
+  }
+  const result = [];
+  if (args.installExplicit && args.install && fs.existsSync(path.join(root, 'package.json'))) {
+    const [command, commandArgs] = helpers.packageInstallArgv(root, `^${helpers.cliVersion()}`);
+    result.push(`${command} ${commandArgs.join(' ')}`);
+  }
+  result.push(arkCommand(root, 'ark-check', '--init'));
+  const host = args.tools ? ` --tools ${args.tools}` : '';
+  result.push(arkCommand(root, 'ark-check', `--install-agent-gates --compact${host}`));
+  result.push(arkCommand(root, 'ark-check', '--plan --json'));
+  result.push(arkCommand(root, 'ark-check', '--coverage --json'));
+  return result;
+}
+
+export function renderStartPreview(preview) {
+  console.log('Ark start preview — no files were changed.');
+  if (preview.analysis) {
+    console.log(`Your project looks like: ${preview.analysis.label} (${preview.analysis.archetype}, confidence ${preview.analysis.confidence}).`);
+  }
+  console.log(`Projected governed coverage: ${preview.projectedCoverage.percent ?? 'unknown'}% (${preview.projectedCoverage.classifiedFiles}/${preview.projectedCoverage.totalFiles} files)`);
+  console.log(`Compact setup budget: ${preview.setupBudget.files}/${preview.setupBudget.maxFiles} files, ${preview.setupBudget.bytes}/${preview.setupBudget.maxBytes} bytes${preview.setupBudget.ok ? '' : ' (exceeded)'}.`);
+  console.log('Files to create/edit/delete:');
+  if (preview.changes.length === 0) console.log('  (none)');
+  for (const change of preview.changes) {
+    console.log(`  ${change.action.padEnd(6)} ${change.path}  ${change.afterHash ?? '(deleted)'}`);
+  }
+  console.log('Commands in the approved setup plan:');
+  for (const command of preview.commands) console.log(`  ${command}`);
+  console.log('Host guarantees:');
+  for (const guarantee of preview.hostGuarantees) console.log(`  ${guarantee}`);
+  if (preview.unresolvedDecisions.length > 0) {
+    console.log('Unresolved decisions:');
+    for (const decision of preview.unresolvedDecisions) console.log(`  ${decision}`);
+  }
+  console.log('Review complete file contents with --json. Apply this plan with: ark start --apply');
+}
+
+export function applyStartPreview(root, preview) {
+  if (!preview.setupBudget?.ok) {
+    throw new Error('Refusing to apply a start plan that exceeds the compact setup budget.');
+  }
+  for (const change of preview.changes) {
+    const target = path.join(root, change.path);
+    const current = fs.existsSync(target) ? fs.readFileSync(target) : null;
+    const currentHash = current ? digest(current) : null;
+    if (currentHash !== change.beforeHash) {
+      throw new Error(`Refusing to apply stale preview: ${change.path} changed after planning.`);
+    }
+    if (change.action === 'delete') {
+      fs.rmSync(target, { force: true });
+      continue;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, Buffer.from(change.afterBase64, 'base64'));
+  }
+}
+
+function planHostRemoval(args, helpers) {
+  const host = args.removeHost;
+  const templateFactory = COMPACT_HOST_TEMPLATES[host];
+  if (!templateFactory) throw new Error(`Unknown compact host: ${host}.`);
+  const changes = [];
+  const unresolvedDecisions = [];
+  for (const [relativePath, expected] of templateFactory(args.root)) {
+    const target = path.join(args.root, relativePath);
+    if (!fs.existsSync(target)) continue;
+    const before = fs.readFileSync(target);
+    if (before.toString('utf8') !== expected) {
+      unresolvedDecisions.push(`${relativePath} was customized and was left untouched.`);
+      continue;
+    }
+    changes.push(change(relativePath, before, null));
+  }
+
+  const agentsPath = path.join(args.root, 'AGENTS.md');
+  if (fs.existsSync(agentsPath)) {
+    const before = fs.readFileSync(agentsPath);
+    if (before.toString('utf8') === compactAgentInstructions(args.root, host)) {
+      changes.push(change('AGENTS.md', before, Buffer.from(compactAgentInstructions(args.root))));
+    } else {
+      unresolvedDecisions.push('AGENTS.md is not the expected compact router and was left untouched.');
+    }
+  }
+
+  const genericMcp = path.join(args.root, '.mcp.json');
+  if (!fs.existsSync(genericMcp)) {
+    changes.push(change('.mcp.json', null, Buffer.from(mcpJson(args.root))));
+  }
+
+  return {
+    version: 1,
+    root: args.root,
+    readOnly: true,
+    mode: 'remove-host',
+    host,
+    analysis: null,
+    projectedCoverage: { percent: null, classifiedFiles: 0, totalFiles: 0 },
+    changes,
+    setupBudget: setupBudget(changes),
+    commands: commands(args.root, args, helpers),
+    hostGuarantees: ['host removal is limited to Ark-owned compact artifacts', 'restore with the displayed --tools command'],
+    unresolvedDecisions,
+  };
+}
+
+export async function planStart(args, helpers) {
+  if (args.removeHost) return planHostRemoval(args, helpers);
+  const root = args.root;
+  const before = treeFiles(root);
+  let recommendation = null;
+  try {
+    const rec = buildArchitectureRecommendation(root);
+    recommendation = {
+      archetype: rec.archetype,
+      label: rec.label,
+      confidence: rec.confidence,
+      mature: rec.mature,
+    };
+  } catch {
+    recommendation = null;
+  }
+  const shadowRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ark-start-preview-'));
+  try {
+    fs.cpSync(root, shadowRoot, {
+      recursive: true,
+      filter: (source) => {
+        const relative = path.relative(root, source).split(path.sep).join('/');
+        return !relative.split('/').some((part) => ['.git', 'node_modules', 'dist', 'coverage'].includes(part));
+      },
+    });
+    const childArgs = ['start', '--root', shadowRoot, '--internal-apply', '--skip-package-manager'];
+    if (args.yes) childArgs.push('--yes');
+    if (args.force) childArgs.push('--force');
+    if (!args.strict) childArgs.push('--no-strict');
+    if (args.installExplicit && args.install) childArgs.push('--install');
+    if (args.installExplicit && !args.install) childArgs.push('--no-install');
+    if (args.tools) childArgs.push('--tools', args.tools);
+    if (args.requireWriteHook) childArgs.push('--require-write-hook', args.requireWriteHook);
+    const planned = spawnSync(process.execPath, [helpers.cliPath, ...childArgs], {
+      cwd: shadowRoot,
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+    if ((planned.status ?? 1) !== 0) {
+      throw new Error(`Unable to produce a safe start plan (exit ${planned.status ?? 1}): ${planned.stderr || planned.stdout}`.trim());
+    }
+    const coverageRun = spawnSync(process.execPath, [helpers.arkCheck, '--root', shadowRoot, '--config', 'ark.config.json', '--coverage', '--json'], { cwd: shadowRoot, encoding: 'utf8' });
+    let coverage = {};
+    try {
+      coverage = JSON.parse(coverageRun.stdout || '{}').coverage || {};
+    } catch {
+      coverage = {};
+    }
+    const afterRaw = treeFiles(shadowRoot);
+    const after = new Map([...afterRaw].map(([file, content]) => [file, normalizedContent(content, shadowRoot, root)]));
+    const changes = [];
+    for (const file of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+      const oldContent = before.get(file);
+      const newContent = after.get(file);
+      if ((oldContent && newContent && oldContent.equals(newContent)) || (!oldContent && !newContent)) continue;
+      changes.push(change(file, oldContent, newContent));
+    }
+    const percent = coverage.governed?.percent ?? null;
+    return {
+      version: 1,
+      root,
+      readOnly: true,
+      analysis: recommendation,
+      projectedCoverage: {
+        percent,
+        classifiedFiles: coverage.governed?.classifiedFiles ?? 0,
+        totalFiles: coverage.governed?.totalFiles ?? coverage.totalFiles ?? 0,
+      },
+      changes,
+      setupBudget: setupBudget(changes),
+      commands: commands(root, args, helpers),
+      hostGuarantees: [
+        args.requireWriteHook ? `Hard-write hook verified for ${args.requireWriteHook}` : 'shared CI merge gate will be installed',
+        'preview phase performs no writes in the target project',
+        'apply writes the exact bytes identified by each afterHash',
+      ],
+      unresolvedDecisions: percent !== null && percent < 90 ? [`Projected governed coverage is ${percent}%; review unclassified files before treating the contract as complete.`] : [],
+    };
+  } finally {
+    fs.rmSync(shadowRoot, { recursive: true, force: true });
+  }
+}

package/bin/lib/ts-resolve.mjs

@@ -203,8 +203,17 @@ export function resolveRelativeFallback(fromFile, specifier) {
  * lookup); edges that resolve outside the root are still skipped.
  */
 export function resolveImport(ts, specifier, containingFile, options, host, root) {
-  const res = ts.resolveModuleName(specifier, containingFile, options, host);
-  let file = res.resolvedModule?.resolvedFileName;
+  let file;
+  // Explicit relative extensions are already unambiguous on disk. Avoid a full TypeScript
+  // resolver walk for the common ESM/CJS form; retain TypeScript as the fallback for aliases,
+  // packages, extensionless imports, and any explicit path that is not an existing file.
+  if (specifier.startsWith('.') && path.extname(specifier)) {
+    file = resolveRelativeFallback(containingFile, specifier);
+  }
+  if (!file) {
+    const res = ts.resolveModuleName(specifier, containingFile, options, host);
+    file = res.resolvedModule?.resolvedFileName;
+  }
   if (!file && specifier.startsWith('.')) {
     file = resolveRelativeFallback(containingFile, specifier);
   }

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

@@ -138,6 +138,10 @@ export function detectWritePathInventory(root) {
       merge
     ),
     cursor: hostRecord([], mcpEvidence(root, '.cursor/mcp.json'), [], merge),
+    // Codex 0.123+ emits PreToolUse for the native apply_patch handler, but some
+    // Code Mode hosts execute deferred nested writes without dispatching that
+    // project hook. Keep the installed hook as best-effort protection; do not
+    // report a hard boundary that cannot be verified for every write surface.
     codex: hostRecord([], codexMcpEvidence(root), [], merge),
   };
 

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 };