ark-runtime-kernel 1.1.0 → 1.2.0

package/README.md

@@ -30,7 +30,7 @@ No code changes. No new runtime. Just a config and a CI line.
 
 ```bash
 npm install -D ark-runtime-kernel typescript
-npx ark-check --init          # infers layers from your existing folders → ark.config.json
+npx ark init                  # asks before generating config, agent gates, and CI templates
 npx ark-check                 # done: cross-layer imports now fail the check
 ```
 
@@ -58,6 +58,19 @@ Then gate your agents (Claude Code shown; [Cursor / Codex / others](docs/ai-gate
 
 > The same `ark.config.json` powers every gate.
 
+Or generate the starter agent and CI gate files:
+
+```bash
+npx ark-check --install-agent-gates
+```
+
+This writes opt-in templates for MCP discovery, Claude/Cursor rules, Codex config notes,
+GitHub Actions, and agent instructions. Existing files are skipped unless you pass
+`--force`.
+
+The package `postinstall` only prints the next command; it never prompts or writes files
+during `npm install`. Use `npx ark init --yes` for non-interactive setup.
+
 ## Why Ark (and not just a linter)?
 
 If you only need import-boundary linting in CI, [dependency-cruiser](https://github.com/sverweij/dependency-cruiser), [eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries), and Nx module boundaries are solid tools. Ark's reason to exist is the **write-time, agent-native half** they don't cover:

package/bin/ark-check.mjs

@@ -22,6 +22,7 @@ function parseArgs(argv) {
     json: false,
     strictConfig: false,
     init: false,
+    installAgentGates: false,
     force: false,
     baseline: undefined,
     updateBaseline: false,
@@ -31,6 +32,7 @@ function parseArgs(argv) {
     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;
@@ -52,6 +54,7 @@ function usage() {
   return [
     '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',
     '',
@@ -82,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');
 }
 
@@ -205,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)
@@ -670,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}`);

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 {