arkgate 4.8.18 → 4.8.20

package/bin/ark-shared.mjs

@@ -875,12 +875,61 @@ const SKIP_DIR_NAMES = new Set([
   '__pycache__',
 ]);
 
+/**
+ * Non-product trees — same convention as the governed check walk
+ * (`isSkippedSourceDir` in scan-files). Start/recommend/discovery must not
+ * treat playground, fixtures, scaffolds, or tests as production architecture.
+ */
+export const NON_PRODUCT_SOURCE_DIR_NAMES = new Set([
+  'bench',
+  'benches',
+  'benchmark',
+  'benchmarks',
+  'docs',
+  'documentation',
+  'example',
+  'examples',
+  'fixture',
+  'fixtures',
+  'testdata',
+  'playground',
+  'scaffold',
+  'scaffolds',
+  '__tests__',
+  '__mocks__',
+  'e2e',
+  'test',
+  'tests',
+]);
+
+export function isNonProductSourceDirName(name) {
+  return NON_PRODUCT_SOURCE_DIR_NAMES.has(name);
+}
+
+export function isNonProductRelativePath(relPath) {
+  return String(relPath)
+    .split(/[/\\]/)
+    .filter(Boolean)
+    .some((token) => NON_PRODUCT_SOURCE_DIR_NAMES.has(token.toLowerCase()));
+}
+
+/** Check-walk skip: vendor/build plus non-product fixture trees. */
+export function isSkippedSourceDir(name) {
+  return (
+    name === 'node_modules' ||
+    name === 'dist' ||
+    name === 'coverage' ||
+    NON_PRODUCT_SOURCE_DIR_NAMES.has(name)
+  );
+}
+
 function dirHasTsSources(dir, maxDepth) {
   try {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       if (entry.isFile() && /\.(tsx?|jsx?|mts|cts)$/i.test(entry.name)) return true;
       if (!entry.isDirectory()) continue;
       if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
+      if (isSkippedSourceDir(entry.name)) continue;
       if (maxDepth > 0 && dirHasTsSources(path.join(dir, entry.name), maxDepth - 1)) return true;
     }
   } catch {
@@ -918,8 +967,14 @@ export function detectTsPackageRoots(root, options = {}) {
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
-      // Skip agent skill asset trees (not app code).
-      if (entry.name === 'skills' || entry.name === 'templates' || entry.name === 'fixtures') continue;
+      // Skip agent skill asset trees and non-product fixture/playground/test trees.
+      if (
+        entry.name === 'skills' ||
+        entry.name === 'templates' ||
+        isSkippedSourceDir(entry.name)
+      ) {
+        continue;
+      }
       const childRel = rel ? `${rel}/${entry.name}` : entry.name;
       visit(path.join(abs, entry.name), childRel, depth + 1);
     }
@@ -944,7 +999,7 @@ export function resolveIncludeRoots(root) {
   const workspaces = detectWorkspaces(root);
   const tsRoots = detectTsPackageRoots(root);
   if (workspaces.length === 0) {
-    if (tsRoots.length > 0) return tsRoots.filter((r) => r !== '.');
+    if (tsRoots.length > 0) return tsRoots.filter((r) => r !== '.' && !isNonProductRelativePath(r));
     return [];
   }
   // Workspaces present: keep them, add TS package roots not covered by a workspace prefix
@@ -960,7 +1015,7 @@ export function resolveIncludeRoots(root) {
       if (fs.existsSync(path.join(root, tr, 'package.json'))) merged.add(tr);
     }
   }
-  return [...merged];
+  return [...merged].filter((entry) => !isNonProductRelativePath(entry));
 }
 
 function isSourceFile(name) {
@@ -982,18 +1037,96 @@ function readJsonc(file) {
 
 function packageRole(rel, pkg) {
   const tokens = rel.toLowerCase().split('/');
-  if (tokens.some((token) => ['docs', 'documentation', 'website', 'examples', 'example', 'tests', 'test', 'fixtures'].includes(token))) {
-    return tokens.some((token) => token.startsWith('doc') || token === 'website')
-      ? 'docs'
-      : tokens.some((token) => token.startsWith('test') || token === 'fixtures')
-        ? 'test'
-        : 'example';
+  if (tokens.some((token) => ['docs', 'documentation', 'website'].includes(token))) {
+    return 'docs';
+  }
+  if (
+    tokens.some((token) =>
+      [
+        'tests',
+        'test',
+        'fixtures',
+        'fixture',
+        'testdata',
+        'e2e',
+        '__tests__',
+        'playground',
+        'scaffold',
+        'scaffolds',
+      ].includes(token)
+    )
+  ) {
+    return 'test';
+  }
+  if (tokens.some((token) => ['examples', 'example'].includes(token))) {
+    return 'example';
   }
   if (pkg?.bin) return 'cli';
   if (pkg?.exports || pkg?.main || pkg?.module || pkg?.types || pkg?.typings) return 'library';
   return 'application';
 }
 
+/** Path tokens already treated as UI app folders in discoverRepoUnits (root scan). */
+export const UI_PACKAGE_PATH_TOKENS = new Set(['web', 'frontend', 'client', 'ui']);
+
+const UI_PACKAGE_DEP_NAMES =
+  /^(react|react-dom|vue|svelte|preact|solid-js|next|@angular\/core|@sveltejs\/kit)$/i;
+
+/** True when a relative source path sits under a conventional UI package folder. */
+export function sourcePathLooksLikeUi(relPath) {
+  return String(relPath ?? '')
+    .toLowerCase()
+    .split(/[/\\]/)
+    .filter((token) => token && token !== '.')
+    .some((token) => UI_PACKAGE_PATH_TOKENS.has(token));
+}
+
+/**
+ * Application/CLI unit that is a UI surface (folder name or UI framework deps).
+ * Used so monorepo start does not park `web/**` on ApplicationOrchestration.
+ */
+export function isUiPackageUnit(unit) {
+  if (!unit || typeof unit !== 'object') return false;
+  if (sourcePathLooksLikeUi(unit.root)) return true;
+  const deps = unit.productionDeps ?? {};
+  return Object.keys(deps).some((name) => UI_PACKAGE_DEP_NAMES.test(String(name).split('/')[0]));
+}
+
+/** Source root of an application unit that should land on Presentation, not Application. */
+export function isUiApplicationSource(unit, sourceRoot) {
+  if (!unit) return sourcePathLooksLikeUi(sourceRoot);
+  const base =
+    unit.root === '.'
+      ? sourceRoot
+      : sourceRoot === '.' || !sourceRoot
+        ? unit.root
+        : `${unit.root}/${sourceRoot}`;
+  return sourcePathLooksLikeUi(base) || isUiPackageUnit(unit);
+}
+
+/**
+ * Monorepo start globs for package units by role. `uiMode: 'ui'` keeps only UI
+ * application roots (web/, frontend/, react/vue/svelte); `'not-ui'` drops them
+ * so they are not parked on ApplicationOrchestration (#288).
+ */
+export function monorepoRoleSourceGlobs(units, roles, { root, domainScoped = false, uiMode } = {}) {
+  if (!root || !Array.isArray(units)) return [];
+  return units
+    .filter((unit) => roles.includes(unit.role) && !(domainScoped && unit.root === '.'))
+    .flatMap((unit) =>
+      (unit.sourceRoots ?? []).map((sourceRoot) => {
+        const base =
+          unit.root === '.' ? sourceRoot : sourceRoot === '.' ? unit.root : `${unit.root}/${sourceRoot}`;
+        if (!base || base === '.') return null;
+        const uiSource = isUiApplicationSource(unit, sourceRoot);
+        if (uiMode === 'ui' && !uiSource) return null;
+        if (uiMode === 'not-ui' && uiSource) return null;
+        return `${base}/**`;
+      })
+    )
+    .filter((pattern) => pattern && (!domainScoped || /^(packages|libs)\//.test(pattern)));
+}
+
 function entrypointDirs(pkg) {
   const values = [];
   const add = (value) => {
@@ -1025,9 +1158,18 @@ export function discoverRepoUnits(root) {
     for (const name of ['tsconfig.json', 'jsconfig.json']) {
       const config = readJsonc(path.join(abs, name));
       const rootDir = config?.compilerOptions?.rootDir;
-      if (typeof rootDir === 'string') roots.add(normalizeRel(rootDir));
+      if (typeof rootDir === 'string' && !/\.(json|jsonc)$/i.test(rootDir)) {
+        const normalizedRootDir = normalizeRel(rootDir);
+        if (!isNonProductRelativePath(normalizedRootDir)) roots.add(normalizedRootDir);
+      }
       for (const ref of config?.references ?? []) {
-        if (typeof ref?.path === 'string') roots.add(normalizeRel(ref.path).replace(/^\.\//, ''));
+        if (typeof ref?.path !== 'string') continue;
+        const relRef = normalizeRel(ref.path).replace(/^\.\//, '');
+        // Project references often point at tsconfig.app.json — that is not a source root.
+        if (!relRef || relRef === '.' || /\.(json|jsonc)$/i.test(relRef)) continue;
+        if (isNonProductRelativePath(relRef)) continue;
+        const absRef = path.join(abs, relRef);
+        if (fs.statSync(absRef, { throwIfNoEntry: false })?.isDirectory()) roots.add(relRef);
       }
     }
     for (const dir of entrypointDirs(pkg)) {
@@ -1067,6 +1209,7 @@ function walkSourceFiles(dir, files = [], depth = 0) {
     // `.github/workflows/` CI dir must not read as an app "workflows"/saga signal, and Ark's
     // own installed `.claude`/`.codex` dirs must not perturb a re-run's recommendation.
     if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('.')) continue;
+    if (isSkippedSourceDir(entry.name)) continue;
     walkSourceFiles(path.join(dir, entry.name), files, depth + 1);
   }
   return files;
@@ -1105,6 +1248,7 @@ function dirExistsAnywhere(root, names) {
       // Skip node_modules/dist and ALL dot-dirs so `.github/workflows/` (CI YAML) can't be read
       // as an app "workflows"/saga signal, and Ark's own `.claude`/`.codex` don't self-perturb.
       if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('.')) continue;
+      if (isSkippedSourceDir(entry.name)) continue;
       if (names.has(entry.name)) return true;
       const child = rel === '.' ? entry.name : `${rel}/${entry.name}`;
       if (child.split('/').length < 8) queue.push(child);
@@ -1139,7 +1283,14 @@ export function collectRepoShapeSignals(root) {
   const pkg = readPackageJson(root);
   const repoUnits = discoverRepoUnits(root);
   const workspaceDirs = detectWorkspaces(root);
-  const workspaces = workspaceDirs.length > 0;
+  // Manifest presence is workspace evidence even when globs parse to no dirs
+  // (pnpm-workspace.yaml without package.json#workspaces is the common case).
+  const workspaces =
+    workspaceDirs.length > 0 ||
+    isPnpmWorkspaceRoot(root) ||
+    isNpmYarnWorkspaceRoot(root) ||
+    fs.existsSync(path.join(root, 'rush.json')) ||
+    fs.existsSync(path.join(root, 'lerna.json'));
   // Include frontend/web/client — common Next monorepo app folders.
   const candidateScanDirs = repoUnits
     .filter((unit) => !['docs', 'example', 'test'].includes(unit.role))
@@ -1362,7 +1513,10 @@ export function collectRepoShapeSignals(root) {
 }
 
 const SIGNAL_WHY = {
-  workspaces: (signals) => `workspace roots declared (${signals.workspaceDirs.join(', ')})`,
+  workspaces: (signals) =>
+    signals.workspaceDirs?.length
+      ? `workspace roots declared (${signals.workspaceDirs.join(', ')})`
+      : 'workspace manifest present (pnpm-workspace.yaml, package.json workspaces, rush, or lerna)',
   tinyTree: (signals) => `few source files (${signals.sourceFileCount})`,
   ui: () => 'UI directories or multiple TSX files present',
   uiHeavy: () => 'substantial UI surface (multiple TSX files)',
@@ -1397,8 +1551,24 @@ const SIGNAL_WHY = {
   expressLike: () => 'HTTP framework dependency (express/fastify/hono/…)',
 };
 
+/**
+ * Playbook labels that claim "without UI" are only honest when uiHeavy is false.
+ * Mirror of the #282 workspace negative-copy overlay: do not invent a new
+ * archetype — rewrite the one-minute label so it cannot contradict the sensors.
+ */
+export function honestArchetypeLabel(label, signals) {
+  if (typeof label !== 'string' || !signals?.uiHeavy) return label;
+  if (!/without UI/i.test(label)) return label;
+  if (signals.workspaces && signals.apiSurface) return 'API-heavy monorepo with UI packages';
+  if (signals.apiSurface) return 'API-heavy repository with a UI surface';
+  return 'Repository with a UI surface';
+}
+
 const NEGATIVE_SIGNAL_WHY = {
-  workspaces: () => 'not a workspace monorepo (penalized for this shape)',
+  workspaces: (signals) =>
+    signals.workspaces
+      ? `workspace monorepo (${signals.workspaceDirs?.join(', ') || 'manifest present'}; this shape prefers a single package)`
+      : 'not a workspace monorepo (penalized for this shape)',
   cli: () => 'CLI bin entry present (penalized for this shape)',
   ui: () => 'UI directories present (penalized for this shape)',
   uiHeavy: () => 'heavy UI surface (penalized for this shape)',
@@ -1582,7 +1752,7 @@ export function scoreArchetypes(signals, playbook) {
     );
     scored.push({
       id,
-      label: def.label,
+      label: honestArchetypeLabel(def.label, signals),
       preset: resolvePreset(def, signals),
       score,
       maxPositive: maxPositive || 1,
@@ -1718,6 +1888,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
       })),
       workspaces: signals.workspaces,
       ui: signals.ui,
+      uiHeavy: signals.uiHeavy,
       apiSurface: signals.apiSurface,
       persistence: signals.persistence,
       jobs: signals.jobs,

package/bin/ark.mjs

@@ -26,10 +26,13 @@ import {
   applyStartPreview,
   emitStartSetupBudgetRefuse,
   evaluateStartSetupBudgetGate,
-  formatStartPackageInstallFailure,
   planStart,
   renderStartPreview,
 } from './lib/start-preview.mjs';
+import {
+  formatStartPackageInstallFailure,
+  runStartPackageInstall,
+} from './lib/start-install-recovery.mjs';
 import { runUpgradeCommand } from './lib/upgrade-command.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
@@ -211,11 +214,6 @@ function cliVersion() {
 
 // packageInstallArgv is imported from ark-shared (workspace-aware -w / -W).
 
-function runCommand(command, commandArgs, cwd) {
-  const result = spawnSync(command, commandArgs, { cwd, stdio: 'inherit', encoding: 'utf8' });
-  return result.status ?? 1;
-}
-
 function runArkCheck(args, options = {}) {
   const result = spawnSync(process.execPath, [arkCheck, ...args], {
     cwd: options.cwd,
@@ -282,13 +280,16 @@ export function ensureProjectArkgateDependency(root, opts = {}) {
   }
   const pinned = pinArkgateDevDependency(root);
   let installStatus = null;
+  let hostOutput = '';
   // Only run the package manager after a successful pin change — avoid surprise
   // network on every start when arkgate is already listed.
   if (runPm && pinned.changed) {
     const [command, commandArgs] = packageInstallArgv(root, pinned.version);
-    installStatus = runCommand(command, commandArgs, root);
+    const install = runStartPackageInstall(command, commandArgs, root);
+    installStatus = install.status;
+    hostOutput = `${install.stdout}\n${install.stderr}`;
   }
-  return { pinned, installStatus };
+  return { pinned, installStatus, hostOutput };
 }
 
 async function resolveArchetypeInteractive(rl, root) {
@@ -503,16 +504,17 @@ async function start(args) {
         const installCommand = `${command} ${commandArgs.join(' ')}`;
         if (!args.json) console.log(`Installing package: ${installCommand}`);
         // Keep stdout clean for --json consumers (package managers are chatty on stdout).
-        const status = args.json
-          ? (spawnSync(command, commandArgs, {
-              cwd: args.root,
-              stdio: ['ignore', 'pipe', 'pipe'],
-              encoding: 'utf8',
-            }).status ?? 1)
-          : runCommand(command, commandArgs, args.root);
-        if (status !== 0) {
-          console.error(formatStartPackageInstallFailure({ exitStatus: status, installCommand }));
-          return status;
+        const install = runStartPackageInstall(command, commandArgs, args.root);
+        if (install.status !== 0) {
+          console.error(
+            formatStartPackageInstallFailure({
+              exitStatus: install.status,
+              installCommand,
+              hostOutput: `${install.stdout}\n${install.stderr}`,
+              packageVersion: cliVersion(),
+            })
+          );
+          return install.status;
         }
       }
     }
@@ -572,7 +574,7 @@ async function start(args) {
     // 2b) Pin arkgate as a project devDependency so CI/npx do not depend on a stale global.
     // Default install=true; only --no-install skips. (installExplicit tracks user override for copy.)
     if (args.install && fs.existsSync(path.join(root, 'package.json'))) {
-      const { pinned, installStatus } = ensureProjectArkgateDependency(root, {
+      const { pinned, installStatus, hostOutput } = ensureProjectArkgateDependency(root, {
         install: true,
         runPackageManager: !args.skipPackageManager,
       });
@@ -584,6 +586,8 @@ async function start(args) {
             formatStartPackageInstallFailure({
               exitStatus: installStatus,
               installCommand: `${command} ${commandArgs.join(' ')}`,
+              hostOutput,
+              packageVersion: cliVersion(),
             })
           );
         }