ark-runtime-kernel 1.0.0 → 1.2.0

package/bin/ark-check.mjs

@@ -22,14 +22,24 @@ function parseArgs(argv) {
     json: false,
     strictConfig: false,
     init: false,
+    installAgentGates: false,
     force: false,
+    baseline: undefined,
+    updateBaseline: false,
   };
   for (let i = 2; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') args.json = true;
     else if (arg === '--strict-config') args.strictConfig = true;
     else if (arg === '--init') args.init = true;
+    else if (arg === '--install-agent-gates') args.installAgentGates = true;
     else if (arg === '--force') args.force = true;
+    else if (arg === '--baseline' || arg === '--update-baseline') {
+      if (arg === '--update-baseline') args.updateBaseline = true;
+      // optional path value: consume the next arg only when it isn't another flag
+      const next = argv[i + 1];
+      args.baseline = next && !next.startsWith('-') ? argv[++i] : '.ark-baseline.json';
+    }
     else if (arg === '--root') args.root = path.resolve(argv[++i]);
     else if (arg === '--config') args.config = argv[++i];
     else if (arg === '--manifest') args.manifest = argv[++i];
@@ -42,10 +52,16 @@ function parseArgs(argv) {
 
 function usage() {
   return [
-    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--json]',
+    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--json] [--baseline [file]]',
     '       ark-check --init [--force]',
+    '       ark-check --install-agent-gates [--force]',
+    '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',
+    'Adopting Ark in an existing codebase? Run --update-baseline once to freeze existing',
+    'violations, commit the baseline file, and gate CI with --baseline: only NEW violations',
+    'fail the check, so the ratchet only moves toward zero.',
+    '',
     '--init scans the project for the built-in layer directory conventions (src/domain,',
     'src/application, src/adapters/persistence, ...) and writes an ark.config.json covering',
     'only the layers that actually exist, with the default rules filtered to those layers.',
@@ -69,6 +85,9 @@ function usage() {
     '',
     'Generate a starter 11-layer config:',
     '  ark-check --print-config eleven-layer > ark.config.json',
+    '',
+    'Install agent + CI enforcement templates:',
+    '  ark-check --install-agent-gates',
   ].join('\n');
 }
 
@@ -192,6 +211,170 @@ function runInit(args) {
   console.log('     (bind its validate_code tool to your agent\'s pre-write hook — see README)');
 }
 
+function ensureDirForFile(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+function writeTemplate(root, relativePath, content, force) {
+  const fullPath = path.join(root, relativePath);
+  if (fs.existsSync(fullPath) && !force) {
+    return { relativePath, status: 'skipped' };
+  }
+  ensureDirForFile(fullPath);
+  fs.writeFileSync(fullPath, content);
+  return { relativePath, status: fs.existsSync(fullPath) ? 'written' : 'written' };
+}
+
+function packageManager(root) {
+  if (fs.existsSync(path.join(root, 'pnpm-lock.yaml'))) {
+    return {
+      cache: 'pnpm',
+      setup: ['corepack enable'],
+      install: 'pnpm install --frozen-lockfile',
+      run: 'pnpm exec ark-check --root . --config ark.config.json --strict-config',
+    };
+  }
+  if (fs.existsSync(path.join(root, 'yarn.lock'))) {
+    return {
+      cache: 'yarn',
+      setup: ['corepack enable'],
+      install: 'yarn install --frozen-lockfile',
+      run: 'yarn ark-check --root . --config ark.config.json --strict-config',
+    };
+  }
+  return {
+    cache: 'npm',
+    setup: [],
+    install: fs.existsSync(path.join(root, 'package-lock.json')) ? 'npm ci' : 'npm install',
+    run: 'npx ark-check --root . --config ark.config.json --strict-config',
+  };
+}
+
+function agentInstructions() {
+  return `# Ark Enforcement
+
+Before editing TypeScript or JavaScript source files:
+
+1. Read the Ark contract from \`ark://manifest\` when the MCP server is available.
+2. Keep source files inside the layer boundaries declared in \`ark.config.json\`.
+3. Do not bypass Ark publishers, event contracts, or source metadata for runtime mutations.
+4. After edits, run \`npx ark-check --root . --config ark.config.json --strict-config\`.
+5. If Ark reports violations, fix the architecture instead of weakening the gate.
+
+The project is only considered Ark-enforced when the write gate, CI gate, and runtime path all pass.
+`;
+}
+
+function mcpJson() {
+  return `${JSON.stringify({
+    mcpServers: {
+      ark: {
+        type: 'stdio',
+        command: 'npx',
+        args: ['ark-mcp', '--root', '.', '--config', 'ark.config.json'],
+      },
+    },
+  }, null, 2)}\n`;
+}
+
+function codexTomlSnippet() {
+  return `[mcp_servers.ark]
+command = "npx"
+args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+`;
+}
+
+function cursorRule() {
+  return `---
+description: Ark architecture contract
+alwaysApply: true
+---
+
+Before writing or editing TypeScript or JavaScript source files, read the
+\`ark://manifest\` resource from the \`ark\` MCP server when available.
+
+Validate the full post-edit file content with the \`validate_code\` tool before
+writing whenever your runtime supports it. After edits, run:
+
+\`\`\`bash
+npx ark-check --root . --config ark.config.json --strict-config
+\`\`\`
+
+If Ark reports violations, fix the architecture instead of bypassing the gate.
+`;
+}
+
+function githubWorkflow(pm) {
+  const setupSteps = pm.setup.map((command) => `      - run: ${command}`).join('\n');
+  return `name: Ark architecture gate
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  ark-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: ${pm.cache}
+${setupSteps ? `${setupSteps}\n` : ''}      - run: ${pm.install}
+      - run: ${pm.run}
+`;
+}
+
+function claudeSettings() {
+  return `${JSON.stringify({
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: 'Write|Edit|MultiEdit',
+          hooks: [
+            {
+              type: 'command',
+              command:
+                'npx ark-mcp --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json',
+            },
+          ],
+        },
+      ],
+    },
+  }, null, 2)}\n`;
+}
+
+function runInstallAgentGates(args) {
+  const root = args.root;
+  const pm = packageManager(root);
+  const templates = [
+    ['AGENTS.md', agentInstructions()],
+    ['.mcp.json', mcpJson()],
+    ['.cursor/mcp.json', mcpJson()],
+    ['.cursor/rules/ark.mdc', cursorRule()],
+    ['.claude/settings.json', claudeSettings()],
+    ['.github/workflows/ark-check.yml', githubWorkflow(pm)],
+    ['docs/ark-codex-config.toml', codexTomlSnippet()],
+  ];
+
+  const results = templates.map(([relativePath, content]) =>
+    writeTemplate(root, relativePath, content, args.force)
+  );
+
+  console.log('Ark agent gate templates:');
+  for (const result of results) {
+    const marker = result.status === 'written' ? 'wrote' : 'skipped';
+    console.log(`  ${marker.padEnd(7)} ${result.relativePath}`);
+  }
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Review the generated files and commit the ones that match your tools.');
+  console.log('  2. Run: npx ark-check --root . --config ark.config.json --strict-config');
+  console.log('  3. Wire Codex manually from docs/ark-codex-config.toml if your host uses ~/.codex/config.toml.');
+}
+
 function readManifest(root, manifestPath) {
   if (!manifestPath) return undefined;
   const fullPath = path.isAbsolute(manifestPath)
@@ -564,6 +747,71 @@ function publishHasSource(ts, node) {
   );
 }
 
+// ponytail: baseline keys exclude the line number so unrelated edits that shift lines
+// don't resurrect frozen violations; the trade-off is that N identical violations in one
+// file collapse to one key.
+function baselineKey(violation) {
+  return [
+    violation.ruleId,
+    violation.file,
+    violation.fromLayer ?? '',
+    violation.toLayer ?? '',
+    violation.target ?? '',
+  ].join('|');
+}
+
+function readBaseline(root, baselinePath) {
+  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
+  if (!fs.existsSync(fullPath)) return { keys: new Set(), fullPath, exists: false };
+  const raw = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+  return { keys: new Set(raw.violations ?? []), fullPath, exists: true };
+}
+
+function writeBaseline(root, baselinePath, violations) {
+  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
+  const keys = [...new Set(violations.map(baselineKey))].sort();
+  fs.writeFileSync(
+    fullPath,
+    `${JSON.stringify({ version: 1, note: 'Frozen ark-check violations. Only NEW violations fail --baseline runs. Regenerate with: ark-check --update-baseline', violations: keys }, null, 2)}\n`
+  );
+  return { fullPath, count: keys.length };
+}
+
+const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
+const color = {
+  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
+  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+};
+
+const FIX_HINTS = {
+  LAYER_IMPORT_VIOLATION:
+    'Depend on a port/interface owned by an inner layer instead, or move this code to a layer allowed to make this import.',
+  LAYER_INTENT_REFERENCE_VIOLATION:
+    'Reference intents through a layer that owns them (e.g. subscribe from an adapter, not from the domain).',
+  RAW_EVENT_PUBLISH:
+    'Define the intent with ark.registry.define(...) and publish through the returned creator.',
+  PUBLISH_MISSING_SOURCE:
+    'Add metadata.source (the publishing intent name) to the publish call.',
+  PUBLISH_SOURCE_LAYER_MISMATCH:
+    'Use a source intent that belongs to the same layer as the publishing file, or move the file.',
+};
+
+function printViolation(violation) {
+  const location = `${violation.file}:${violation.line}`;
+  console.error(`${color.red('✖')} ${color.bold(violation.ruleId)}  ${location}`);
+  if (violation.fromLayer && violation.toLayer) {
+    const target = violation.target ? `  ${color.dim(`(${violation.target})`)}` : '';
+    console.error(`  ${violation.fromLayer} → ${violation.toLayer}${target}`);
+  }
+  console.error(`  ${violation.message}`);
+  const hint = FIX_HINTS[violation.ruleId];
+  if (hint) console.error(`  ${color.dim(`fix: ${hint}`)}`);
+  console.error('');
+}
+
 function moduleSpecifierFromCall(ts, node) {
   if (!ts.isCallExpression(node)) return undefined;
 
@@ -592,6 +840,10 @@ async function main() {
     runInit(args);
     return;
   }
+  if (args.installAgentGates) {
+    runInstallAgentGates(args);
+    return;
+  }
   if (args.printConfig) {
     if (args.printConfig !== 'eleven-layer') {
       console.error(`Unknown config profile: ${args.printConfig}`);
@@ -733,38 +985,82 @@ async function main() {
     visit(sourceFile);
   }
 
+  if (args.updateBaseline) {
+    const { fullPath, count } = writeBaseline(root, args.baseline, violations);
+    console.log(`Wrote ${fullPath} with ${count} frozen violation key(s).`);
+    console.log('Commit it and gate CI with: ark-check --baseline (only NEW violations fail).');
+    return;
+  }
+
+  let suppressed = [];
+  let activeViolations = violations;
+  let staleBaselineKeys = 0;
+  if (args.baseline) {
+    const baseline = readBaseline(root, args.baseline);
+    if (baseline.exists) {
+      suppressed = violations.filter((violation) => baseline.keys.has(baselineKey(violation)));
+      activeViolations = violations.filter(
+        (violation) => !baseline.keys.has(baselineKey(violation))
+      );
+      const currentKeys = new Set(violations.map(baselineKey));
+      staleBaselineKeys = [...baseline.keys].filter((key) => !currentKeys.has(key)).length;
+    } else {
+      warnings.push(
+        configWarning(
+          'BASELINE_NOT_FOUND',
+          `Baseline file not found: ${baseline.fullPath}. Generate it with: ark-check --update-baseline`
+        )
+      );
+    }
+  }
+
+  const ok = activeViolations.length === 0 && (!args.strictConfig || warnings.length === 0);
+
   if (args.json) {
     console.log(JSON.stringify({
-      ok: violations.length === 0 && (!args.strictConfig || warnings.length === 0),
-      violations,
+      ok,
+      violations: activeViolations,
+      suppressedViolations: suppressed.length,
+      staleBaselineKeys,
       warnings,
     }, null, 2));
-  } else if (violations.length === 0) {
+  } else {
     for (const warning of warnings) {
-      console.error(`warning ${warning.ruleId} ${warning.message}`);
+      console.error(`${color.yellow('warning')} ${warning.ruleId} ${warning.message}`);
     }
-    if (warnings.length === 0) {
-      console.log('Ark check passed.');
-    } else if (args.strictConfig) {
-      console.error(`Ark check failed with ${warnings.length} config warning(s).`);
-    } else {
-      console.log(`Ark check passed with ${warnings.length} config warning(s).`);
+    for (const violation of activeViolations) {
+      printViolation(violation);
     }
-  } else {
-    for (const warning of warnings) {
-      console.error(`warning ${warning.ruleId} ${warning.message}`);
+
+    const baselineNote =
+      suppressed.length > 0 ? ` (${suppressed.length} suppressed by baseline)` : '';
+    if (staleBaselineKeys > 0) {
+      console.error(
+        color.dim(
+          `${staleBaselineKeys} baseline entr(y/ies) no longer occur — tighten the ratchet with: ark-check --update-baseline`
+        )
+      );
     }
-    for (const violation of violations) {
+    if (activeViolations.length === 0) {
+      if (warnings.length === 0) {
+        console.log(`${color.green('✔')} Ark check passed.${baselineNote}`);
+      } else if (args.strictConfig) {
+        console.error(
+          `${color.red('✖')} Ark check failed with ${warnings.length} config warning(s).${baselineNote}`
+        );
+      } else {
+        console.log(
+          `${color.green('✔')} Ark check passed with ${warnings.length} config warning(s).${baselineNote}`
+        );
+      }
+    } else {
       console.error(
-        `${violation.file}:${violation.line} ${violation.ruleId} ${violation.message}`
+        `${color.red('✖')} ${activeViolations.length} violation(s).${baselineNote}`
       );
     }
   }
 
-  process.exitCode =
-    violations.length === 0 && (!args.strictConfig || warnings.length === 0)
-      ? 0
-      : 1;
+  process.exitCode = ok ? 0 : 1;
 }
 
 main().catch((error) => {

package/bin/ark-postinstall.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+if (process.env.ARK_POSTINSTALL_SILENT === '1') {
+  process.exit(0);
+}
+
+console.log(`Ark installed, but not enforced yet.
+Run: npx ark init
+
+For non-interactive setup:
+Run: npx ark init --yes
+`);

package/bin/ark.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline/promises';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const arkCheck = path.join(here, 'ark-check.mjs');
+
+function parseArgs(argv) {
+  const args = {
+    command: argv[2],
+    root: process.cwd(),
+    yes: false,
+    force: false,
+    strict: true,
+    help: false,
+  };
+
+  for (let i = 3; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--root') args.root = path.resolve(argv[++i]);
+    else if (arg === '--yes' || arg === '-y') args.yes = true;
+    else if (arg === '--force') args.force = true;
+    else if (arg === '--no-strict') args.strict = false;
+    else if (arg === '--help' || arg === '-h') args.help = true;
+  }
+
+  return args;
+}
+
+function usage() {
+  return `Usage:
+  ark init [--root <project>] [--yes] [--force] [--no-strict]
+
+Commands:
+  init   Configure Ark project enforcement with explicit prompts.
+
+Options:
+  --yes       Non-interactive defaults: create config if needed, install gate templates, run strict check.
+  --force     Allow generated files to overwrite existing files.
+  --no-strict Skip the final strict ark-check run.
+`;
+}
+
+function runArkCheck(args, options = {}) {
+  const result = spawnSync(process.execPath, [arkCheck, ...args], {
+    cwd: options.cwd,
+    stdio: options.stdio ?? 'inherit',
+    encoding: 'utf8',
+  });
+  return result.status ?? 1;
+}
+
+async function askYesNo(rl, question, defaultYes = true) {
+  const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] ';
+  const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase();
+  if (!answer) return defaultYes;
+  return answer === 'y' || answer === 'yes';
+}
+
+async function init(args) {
+  const root = args.root;
+  const configPath = path.join(root, 'ark.config.json');
+  const rl = args.yes
+    ? null
+    : readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    let shouldInit = !fs.existsSync(configPath);
+    if (fs.existsSync(configPath)) {
+      shouldInit = args.force
+        ? true
+        : args.yes
+          ? false
+          : await askYesNo(rl, 'ark.config.json already exists. Regenerate it?', false);
+    }
+
+    if (shouldInit) {
+      const initArgs = ['--root', root, '--init'];
+      if (args.force) initArgs.push('--force');
+      const status = runArkCheck(initArgs, { cwd: root });
+      if (status !== 0) return status;
+    } else {
+      console.log('Skipped ark.config.json generation.');
+    }
+
+    const installGates = args.yes || await askYesNo(rl, 'Configure agent and CI gate templates?', true);
+    if (installGates) {
+      const gateArgs = ['--root', root, '--install-agent-gates'];
+      if (args.force) gateArgs.push('--force');
+      const status = runArkCheck(gateArgs, { cwd: root });
+      if (status !== 0) return status;
+    }
+
+    const runStrict =
+      args.strict && (args.yes || await askYesNo(rl, 'Run strict architecture check now?', true));
+    if (runStrict) {
+      return runArkCheck(
+        ['--root', root, '--config', 'ark.config.json', '--strict-config'],
+        { cwd: root }
+      );
+    }
+
+    console.log('Ark init complete. Run `npx ark-check --root . --config ark.config.json --strict-config` before merging.');
+    return 0;
+  } finally {
+    rl?.close();
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.help || !args.command) {
+    console.log(usage());
+    return 0;
+  }
+
+  if (args.command === 'init') {
+    return init(args);
+  }
+
+  console.error(`Unknown command: ${args.command}`);
+  console.error(usage());
+  return 2;
+}
+
+process.exitCode = await main();

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/version.ts
-var version = "1.0.0";
+var version = "1.2.0";
 
 // src/kernel/intent/IntentRegistry.ts
 var IntentRegistry = class {
@@ -1105,6 +1105,12 @@ function createEventBus(options) {
 }
 
 // src/kernel/event-contracts/EventContractRegistry.ts
+function formatStandardSchemaPath(path) {
+  if (!path || path.length === 0) return void 0;
+  return path.map(
+    (segment) => typeof segment === "object" && segment !== null && "key" in segment ? String(segment.key) : String(segment)
+  ).join(".");
+}
 function actualType(value) {
   if (Array.isArray(value)) return "array";
   if (value === null) return "object";
@@ -1249,6 +1255,25 @@ var EventContractRegistryImpl = class {
         }
       }
     }
+    if (contract.standardSchema) {
+      const result = contract.standardSchema["~standard"].validate(event.payload);
+      if (result instanceof Promise) {
+        issues.push({
+          intent: event.intent,
+          version: contract.version,
+          message: "Standard Schema validator returned a Promise; event contract validation is synchronous."
+        });
+      } else if (result.issues) {
+        for (const issue of result.issues) {
+          issues.push({
+            intent: event.intent,
+            version: contract.version,
+            field: formatStandardSchemaPath(issue.path),
+            message: issue.message
+          });
+        }
+      }
+    }
     return { ok: issues.length === 0, contract, issues };
   }
   clear() {