arkgate 2.13.0 → 3.0.1

package/bin/ark.mjs

@@ -20,6 +20,8 @@ import {
 } 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');
@@ -58,6 +60,12 @@ 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,
@@ -79,7 +87,19 @@ 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++);
@@ -97,14 +117,13 @@ function parseArgs(argv) {
 
 function usage() {
   return `Usage:
-  ark start   [--root <project>] [--tools <list>] [--require-write-hook <host>] [--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>] [--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
@@ -116,14 +135,19 @@ 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.
@@ -229,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.
@@ -410,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;
@@ -423,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(
@@ -465,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.`);
@@ -480,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).');
     }
 
@@ -494,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')) ||
@@ -510,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(', ')}.`
@@ -527,16 +586,16 @@ 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);
@@ -687,7 +746,7 @@ async function start(args) {
       );
     }
     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 {
@@ -764,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,