arkgate 2.12.0 → 3.0.0

package/bin/ark.mjs

@@ -19,6 +19,9 @@ import {
   resolveOperatingMode,
 } from './ark-shared.mjs';
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
+import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
+import { applyStartPreview, planStart, renderStartPreview } from './lib/start-preview.mjs';
+import { detectActiveAgentHost } from './lib/skill-install.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -57,6 +60,13 @@ function parseArgs(argv) {
     force: false,
     strict: true,
     install: true,
+    installExplicit: false,
+    apply: false,
+    json: false,
+    internalApply: false,
+    skipPackageManager: false,
+    removeHost: undefined,
+    requireWriteHook: undefined,
     help: false,
     version: false,
   };
@@ -77,10 +87,25 @@ function parseArgs(argv) {
     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 === '--no-install') args.install = false;
+    else if (arg === '--install') {
+      args.install = true;
+      args.installExplicit = true;
+    }
+    else if (arg === '--no-install') {
+      args.install = false;
+      args.installExplicit = true;
+    }
+    else if (arg === '--apply') args.apply = true;
+    else if (arg === '--json') args.json = true;
+    else if (arg === '--internal-apply') args.internalApply = true;
+    else if (arg === '--skip-package-manager') args.skipPackageManager = true;
+    else if (arg === '--remove-host') args.removeHost = requireValue(arg, i++).trim().toLowerCase();
     else if (arg === '--preset') args.preset = requireValue(arg, i++);
     else if (arg === '--archetype') args.archetype = requireValue(arg, i++);
     else if (arg === '--tools') args.tools = requireValue(arg, i++);
+    else if (arg === '--require-write-hook') {
+      args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
+    }
     else if (arg === '--help' || arg === '-h' || arg === 'help') args.help = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
     else if (!arg.startsWith('-') && args.command === undefined) args.command = arg;
@@ -92,14 +117,13 @@ function parseArgs(argv) {
 
 function usage() {
   return `Usage:
-  ark start   [--root <project>] [--yes]
+  ark start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
   ark init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture]
-              [--archetype <playbook-id>] [--tools <list>] [--yes] [--force] [--no-strict]
+              [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
   ark upgrade [--root <project>] [--no-install] [--no-strict]
 
 Commands:
-  start     New here? The guided setup. Looks at your project, suggests a shape in
-            plain language, sets up the guardrails, and shows a plan — no code changed.
+  start     New here? Analyze and preview the complete setup. Read-only unless --apply.
   init      Configure Ark project enforcement with explicit prompts.
   upgrade   One command to update Ark: bump the package to @latest, refresh gate
             templates + /ark-* skills (and Codex home prompts), migrate command
@@ -111,14 +135,22 @@ Options:
                (Also the implicit default when stdin/stdout are not a TTY — agents never hang on prompts.)
   --force      Allow generated files to overwrite existing files.
   --no-strict  Skip the final strict ark-check run.
+  --install    Add arkgate to package.json explicitly before applying a start plan.
   --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
+  --apply       Apply the mutations shown by the start preview.
+  --json        Emit the start preview as deterministic machine-readable JSON.
   --preset     Start from a named architecture preset instead of detection.
   --archetype  Application shape from templates/architecture-playbook.json (maps to the matching preset).
                Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
                worker-pipeline, event-coordinator, integration-bridge, multi-app-workspace, prototype-spike,
                vertical-slice-product, ddd-bounded-contexts.
-  --tools      Comma-separated agents to gate (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
-               Omit to auto-detect from each tool's config dir, falling back to claude+cursor+codex+grok.
+  --tools      One active agent host for start (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
+               Omit to use the active host; an unknown host creates only the shared compact router.
+  --remove-host <host>
+               Preview or apply removal of that compact host integration; re-add it with --tools <host>.
+  --require-write-hook <host>
+               Require and verify a hard local write hook for Claude or Grok. Cursor/Codex are
+               advisory-write plus hard CI merge only; impossible requests fail before any write.
 
 Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
 Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.
@@ -203,7 +235,7 @@ async function upgrade(args) {
   }
   console.log('\n4/4  Verifying architecture…');
   return runArkCheck(
-    ['--root', root, '--config', 'ark.config.json', '--strict-config'],
+    ['--root', root, '--config', 'ark.config.json', '--strict-merge'],
     { cwd: root }
   );
 }
@@ -221,6 +253,25 @@ function isInteractiveTty() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
+async function resolveStartHost(args) {
+  if (args.tools || args.removeHost) return args.tools;
+  const active = detectActiveAgentHost();
+  if (!isInteractiveTty() || args.yes) return active ?? undefined;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (
+      await rl.question(
+        `Which agent should receive Ark's compact router? [${active ?? 'skip for now'}] `
+      )
+    )
+      .trim()
+      .toLowerCase();
+    return answer || active || undefined;
+  } finally {
+    rl.close();
+  }
+}
+
 /**
  * True when prompts should be skipped and guided defaults applied.
  * Agents typically have no TTY — never call readline on a null interface.
@@ -365,6 +416,9 @@ async function init(args) {
     if (installGates) {
       const gateArgs = ['--root', root, '--install-agent-gates'];
       if (args.tools) gateArgs.push('--tools', args.tools);
+      if (args.requireWriteHook) {
+        gateArgs.push('--require-write-hook', args.requireWriteHook);
+      }
       if (args.force) gateArgs.push('--force');
       const status = runArkCheck(gateArgs, { cwd: root });
       if (status !== 0) return status;
@@ -374,14 +428,15 @@ async function init(args) {
       args.strict &&
       (nonInteractive || (await askYesNo(rl, 'Run strict architecture check now?', true)));
     if (runStrict) {
-      return runArkCheck(
-        ['--root', root, '--config', 'ark.config.json', '--strict-config'],
-        { cwd: root }
-      );
+      const strictArgs = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
+      if (args.requireWriteHook) {
+        strictArgs.push('--require-write-hook', args.requireWriteHook);
+      }
+      return runArkCheck(strictArgs, { cwd: root });
     }
 
     console.log(
-      `Ark init complete. Run \`${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}\` before merging.`
+      `Ark init complete. Run \`${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-merge')}\` before merging.`
     );
     if (archetype) {
       console.log(`Shape: ${archetype}. Plan: ${arkCommand(root, 'ark-check', '--recommend')}`);
@@ -398,9 +453,24 @@ async function init(args) {
 
 // `ark start` — the guided entry point (co-pilot Phase G). One command takes a newcomer from
 // "I have a project" to "governed, with a plan" in plain language, without knowing any skill
-// names: look at the code → suggest a shape → set up the guardrails → show the plan. It only
+// names: look at the code → suggest a shape → set up one compact host router → show the plan. It only
 // orchestrates existing steps (recommend → init → --plan) and frames each in outcome terms.
 async function start(args) {
+  if (!args.internalApply) {
+    args.tools = await resolveStartHost(args);
+    const preview = await planStart(args, {
+      arkCheck,
+      cliPath: fileURLToPath(import.meta.url),
+      cliVersion,
+      packageInstallArgv,
+    });
+    if (args.json) console.log(JSON.stringify(preview, null, 2));
+    else renderStartPreview(preview);
+    if (!args.apply) return 0;
+    applyStartPreview(args.root, preview);
+    if (!args.json) console.log(`Applied ${preview.changes.length} previewed mutation(s).`);
+    return 0;
+  }
   const root = args.root;
   const nonInteractive = shouldUseNonInteractiveDefaults(args);
   const interactive = !nonInteractive;
@@ -411,10 +481,10 @@ async function start(args) {
   try {
     console.log("Let's set up Ark for your project.");
     console.log(
-      "I'll walk the tree, freeze a day-zero architecture picture, then set up guardrails and show a plan."
+      "I'll walk the tree, create a compact host-specific guardrail setup, then show a plan."
     );
     console.log(
-      'Nothing in your product code is changed — only Ark config, then origin snapshot, then agent/CI templates.'
+      'Nothing in your product code is changed — only Ark config, one active-host router, and a CI template.'
     );
     if (nonInteractive && !args.yes) {
       console.log(
@@ -453,10 +523,10 @@ async function start(args) {
     }
 
     // 2b) Pin arkgate as a project devDependency so CI/npx do not depend on a stale global.
-    if (args.install !== false && fs.existsSync(path.join(root, 'package.json'))) {
+    if (args.installExplicit && args.install && fs.existsSync(path.join(root, 'package.json'))) {
       const { pinned, installStatus } = ensureProjectArkgateDependency(root, {
         install: true,
-        runPackageManager: true,
+        runPackageManager: !args.skipPackageManager,
       });
       if (pinned.changed) {
         console.log(`  Pinned arkgate@${pinned.version} in package.json devDependencies.`);
@@ -468,7 +538,7 @@ async function start(args) {
       } else if (pinned.reason === 'already-present') {
         console.log(`  arkgate already in package.json (${pinned.version}).`);
       }
-    } else if (args.install === false) {
+    } else if (args.installExplicit && args.install === false) {
       console.log('  Skipping arkgate package pin (--no-install).');
     }
 
@@ -482,10 +552,11 @@ async function start(args) {
       const preset = archetype ? resolveArchetypePreset(archetype).preset : undefined;
       const includeRoots = resolveIncludeRoots(root);
       const tsPackages = detectTsPackageRoots(root);
+      const nestedTsPackages = tsPackages.filter((entry) => entry !== '.');
       const workspaces = detectWorkspaces(root);
       const looksLikeMonorepo =
         includeRoots.length > 0 ||
-        tsPackages.length > 0 ||
+        nestedTsPackages.length > 0 ||
         workspaces.length > 0 ||
         fs.existsSync(path.join(root, 'rush.json')) ||
         fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) ||
@@ -498,9 +569,9 @@ async function start(args) {
         const useUi =
           rec?.preset === 'feature-sliced' ||
           rec?.archetype === 'frontend-surface' ||
-          (tsPackages.length > 0 && includeRoots.length === 0 && !rec?.mature);
-        initArgs.push('--preset', useUi && tsPackages.length <= 3 ? 'ui-surface' : 'monorepo');
-        const shown = includeRoots.length > 0 ? includeRoots : tsPackages;
+          (nestedTsPackages.length > 0 && includeRoots.length === 0 && !rec?.mature);
+        initArgs.push('--preset', useUi && nestedTsPackages.length <= 3 ? 'ui-surface' : 'monorepo');
+        const shown = includeRoots.length > 0 ? includeRoots : nestedTsPackages;
         console.log(
           shown.length > 0
             ? `  Multi-package / TS package layout detected — profile include: ${shown.join(', ')}.`
@@ -515,19 +586,23 @@ async function start(args) {
       console.log('  Found an existing ark.config.json — keeping it.');
     }
 
-    // 4) Day-zero origin — freeze the architecture picture *before* agent docs / CI / skills.
-    // Later --report runs show evolution vs this snapshot. Idempotent (origin once).
+    // 4) Compact start deliberately avoids reports/history and copied skills. A report can
+    // be requested later, after the small host-specific setup is accepted.
     console.log('');
-    freezeDayZeroOrigin(root);
+    console.log('Skipping day-zero report archive in compact start (run ark-check --report later if wanted).');
 
-    // 5) Agent + CI gate templates (docs, hooks, skills) — after origin is frozen.
+    // 5) Agent + CI gate templates for exactly one active host.
     console.log('');
     console.log('Installing agent and CI gate templates…');
     {
-      const gateArgs = ['--root', root, '--install-agent-gates'];
+      const gateArgs = ['--root', root, '--install-agent-gates', '--compact'];
       if (args.tools) gateArgs.push('--tools', args.tools);
+      if (args.requireWriteHook) {
+        gateArgs.push('--require-write-hook', args.requireWriteHook);
+      }
       if (args.force) gateArgs.push('--force');
-      runArkCheck(gateArgs, { cwd: root });
+      const status = runArkCheck(gateArgs, { cwd: root });
+      if (status !== 0) return status;
     }
 
     // 6) Show the plan: what's safe to auto-fix vs what needs a decision.
@@ -664,14 +739,14 @@ async function start(args) {
       console.log('     → explore first, dual plan (remediation + pattern bets), safe fixes, leave gates on.');
     }
     console.log(`  2. Status anytime: ${arkCommand(root, 'ark-check', '--doctor')}`);
-    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}`);
+    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-merge')}`);
     if (mode === 'adapt' && planOk && !falseGreenGap) {
       console.log(
         `  4. When green but cores still optional: ${arkCommand(root, 'ark-check', '--ratchet-cores')} → honest ENFORCE`
       );
     }
     console.log('');
-    console.log('Day-zero origin is under .ark/reports/origin.* — re-run --report later for evolution.');
+    console.log('Optional later: ark-check --report ark-report.html (captures a day-zero/evolution report).');
     console.log('Optional later: --plan · --coverage · /ark-explore · /ark-fix · /ark-place · ark upgrade');
     return 0;
   } finally {
@@ -696,6 +771,25 @@ async function main() {
     return 0;
   }
 
+  if (args.requireWriteHook && !['start', 'init'].includes(args.command)) {
+    console.error('--require-write-hook is supported by ark start and ark init.');
+    return 2;
+  }
+  const enforcement = validateHardWriteRequest({
+    root: args.root,
+    host: args.requireWriteHook,
+    tools: args.tools,
+    force: args.force,
+  });
+  if (!enforcement.ok) {
+    console.error(enforcement.error);
+    return 2;
+  }
+  if (enforcement.host) {
+    args.requireWriteHook = enforcement.host;
+    if (!args.tools) args.tools = enforcement.tools.join(',');
+  }
+
   if (args.command === 'start') {
     try {
       return await start(args);
@@ -729,9 +823,15 @@ async function main() {
 }
 
 // Only run when executed as the CLI entry (not when imported by unit tests).
-const isMain =
-  Boolean(process.argv[1]) &&
-  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+function entryPath(file) {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return path.resolve(file);
+  }
+}
+
+const isMain = Boolean(process.argv[1]) && entryPath(process.argv[1]) === entryPath(fileURLToPath(import.meta.url));
 if (isMain) {
   process.exitCode = await main();
 }

package/bin/lib/adapter-contract.mjs

@@ -0,0 +1,93 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/adapterContract.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/adapter-contract.mjs). Zero Node I/O.
+ */
+
+export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.0';
+function text(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function positiveInteger(value, fallback) {
+    return Number.isInteger(value) && Number(value) > 0 ? Number(value) : fallback;
+}
+export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
+    const ruleId = text(violation.ruleId) ?? text(violation.code) ?? 'ARK_UNKNOWN';
+    const severity = violation.severity === 'warning' ? 'warning' : fallbackSeverity;
+    const evidence = {
+        ...(text(violation.target) ? { target: text(violation.target) } : {}),
+        ...(text(violation.fromLayer) ? { fromLayer: text(violation.fromLayer) } : {}),
+        ...(text(violation.toLayer) ? { toLayer: text(violation.toLayer) } : {}),
+        ...(typeof violation.typeOnly === 'boolean' ? { typeOnly: violation.typeOnly } : {}),
+    };
+    return {
+        ruleId,
+        severity,
+        message: text(violation.message) ?? ruleId,
+        location: {
+            file: text(violation.file) ?? '<unknown>',
+            line: positiveInteger(violation.line, 1),
+            column: positiveInteger(violation.column, 1),
+        },
+        evidence,
+    };
+}
+export function createAdapterResult(input) {
+    return {
+        schemaVersion: ARK_ANALYSIS_RESULT_SCHEMA_VERSION,
+        valid: input.valid,
+        diagnostics: [
+            ...(input.violations ?? []).map((item) => toAdapterDiagnostic(item, 'error')),
+            ...(input.warnings ?? []).map((item) => toAdapterDiagnostic(item, 'warning')),
+        ],
+    };
+}
+export const ARK_ANALYSIS_RESULT_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://unpkg.com/arkgate@2/schemas/ark.analysis-result.schema.json',
+    title: 'ArkGate analysis result',
+    type: 'object',
+    additionalProperties: false,
+    required: ['schemaVersion', 'valid', 'diagnostics'],
+    properties: {
+        schemaVersion: { const: ARK_ANALYSIS_RESULT_SCHEMA_VERSION },
+        valid: { type: 'boolean' },
+        diagnostics: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['ruleId', 'severity', 'message', 'location', 'evidence'],
+                properties: {
+                    ruleId: { type: 'string', minLength: 1 },
+                    severity: { enum: ['error', 'warning'] },
+                    message: { type: 'string', minLength: 1 },
+                    location: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['file', 'line', 'column'],
+                        properties: {
+                            file: { type: 'string', minLength: 1 },
+                            line: { type: 'integer', minimum: 1 },
+                            column: { type: 'integer', minimum: 1 },
+                        },
+                    },
+                    evidence: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            target: { type: 'string' },
+                            fromLayer: { type: 'string' },
+                            toLayer: { type: 'string' },
+                            typeOnly: { type: 'boolean' },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};

package/bin/lib/agent-gates.mjs

@@ -45,6 +45,7 @@ export {
   packageScriptsHaveTypecheck,
   treeHasTypecheckScript,
   ensureTypecheckScript,
+  compactRouterHost,
   REQUIRED_GATE_FILES,
   hasArkWorkflow,
   missingGates,
@@ -76,6 +77,8 @@ export {
   normalizeToolsList,
   resolveTools,
   KNOWN_TOOLS,
+  detectActiveAgentHost,
+  codexConcernIsActive,
   arkPackageVersion,
   stampSkill,
   installedSkillVersion,
@@ -95,6 +98,16 @@ export {
   collectAdoptionGaps,
 } from './mcp-adoption.mjs';
 
+export {
+  detectPreCommitArk,
+  detectCiEnforcement,
+  detectConfigGateDrift,
+  jobIdsThatRunArkCheck,
+  isArkRequiredStatusCheck,
+  reportGithubBranchProtection,
+  collectWeakestLinkGaps,
+} from './weakest-link.mjs';
+
 export {
   staleRunnerGateFiles,
   warnLockfileConflict,