arkgate 4.8.19 → 4.8.21

package/bin/ark-layer-match.mjs

@@ -215,18 +215,192 @@ export function layerForRelativePath(relPath, layers) {
  * Includes the parent folder so `features/auth` ≠ `modules/auth`.
  * Identity is case-normalized for portable results across filesystems.
  * `src/features/auth/api.ts` + folders `["features"]` → `"features/auth"`.
+ *
+ * A bare name stays that unanchored one-segment match. The child segment is
+ * never the filename, so a flat file under the parent is not its own slice.
+ * A starred prefix (`lib` / `features` / `*` / `*`) reuses the shared-root
+ * anchor: it must sit at offset 0, or at offset 1 after `src/` or `app/`.
+ * With `sliceIdentity` `"path"` (the default) the slice id includes the
+ * literal prefix plus the star bindings (`lib/features/projects/rfi`), so
+ * parallel trees get different ids. With `"stars"` it is the last literal
+ * plus those star bindings. A star never binds the filename; a file directly
+ * under the last bound directory keeps that directory as its slice.
  */
-export function sliceIdForPath(relPath, sliceFolders) {
+export function sliceIdForPath(relPath, sliceFolders, sliceIdentity) {
     if (!sliceFolders?.length)
         return undefined;
+    const identity = sliceIdentity === 'stars' ? 'stars' : 'path';
     const parts = String(relPath)
         .split(/[/\\]/)
         .filter(Boolean);
-    const folders = new Set(sliceFolders.map((s) => String(s).toLowerCase()));
-    for (let i = 0; i < parts.length - 1; i += 1) {
-        if (folders.has(parts[i].toLowerCase())) {
-            return `${parts[i].toLowerCase()}/${parts[i + 1].toLowerCase()}`;
+    if (parts.length === 0)
+        return undefined;
+    const bare = new Set();
+    for (const raw of sliceFolders) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            continue;
+        if (isAnchoredSliceEntry(raw)) {
+            const anchored = anchoredSliceId(parts, raw, identity);
+            if (anchored)
+                return anchored;
+            continue;
+        }
+        if (!raw.includes('/') && !raw.includes('\\') && !raw.includes('*')) {
+            bare.add(raw.toLowerCase());
+        }
+    }
+    return bareSliceId(parts, bare);
+}
+/** A starred prefix with a real leading directory, not a bare name and not `*`. */
+function isAnchoredSliceEntry(entry) {
+    const segments = entry.split(/[/\\]/).filter((part) => part.length > 0);
+    if (segments.length < 2)
+        return false;
+    if (segments[0] === '*' || segments[0] === '**')
+        return false;
+    return segments.some((part) => part === '*');
+}
+function anchoredSliceId(parts, raw, identity) {
+    const pattern = raw
+        .split(/[/\\]/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.toLowerCase());
+    const offsets = anchorOffsets(parts, pattern[0] ?? '');
+    for (const offset of offsets) {
+        const id = bindAnchoredSlice(parts, pattern, offset, identity);
+        if (id)
+            return id;
+    }
+    return undefined;
+}
+/**
+ * Walk an anchored pattern from `offset`. Literals must match. Each matching
+ * literal is part of the bound segments, and each `*` binds one directory.
+ * A star stops before the filename; leftover stars then end the id at the
+ * last directory that did bind. Segments `lib` / `features` / `*` / `*`
+ * (the pattern `lib/features` plus two stars) therefore yield
+ * `lib/features/projects/rfi` under `path`.
+ *
+ * `path` returns every bound segment (literal prefix plus star bindings), so
+ * a parallel tree (`components` / `features` / `*` / `*`) gets a different
+ * id. `stars` drops the literal prefix before the last literal and keeps
+ * that literal plus the star bindings.
+ */
+function bindAnchoredSlice(parts, pattern, offset, identity = 'path') {
+    const bound = [];
+    let lastLiteralAt = -1;
+    let index = offset;
+    for (let pi = 0; pi < pattern.length; pi += 1) {
+        const segment = pattern[pi];
+        if (segment === '*') {
+            if (index >= parts.length - 1) {
+                for (let rest = pi; rest < pattern.length; rest += 1) {
+                    if (pattern[rest] !== '*')
+                        return undefined;
+                }
+                break;
+            }
+            bound.push(parts[index].toLowerCase());
+            index += 1;
+            continue;
+        }
+        if (segment === '**' || index >= parts.length)
+            return undefined;
+        if (parts[index].toLowerCase() !== segment)
+            return undefined;
+        bound.push(parts[index].toLowerCase());
+        lastLiteralAt = bound.length - 1;
+        index += 1;
+    }
+    if (bound.length === 0)
+        return undefined;
+    if (identity === 'stars') {
+        if (lastLiteralAt < 0)
+            return undefined;
+        return bound.slice(lastLiteralAt).join('/');
+    }
+    return bound.join('/');
+}
+/**
+ * Doctor warning input. Silent unless `sliceIdentity` is `"stars"` and two
+ * different anchored prefixes share a stem (last literal plus the stars after it).
+ */
+export function sliceIdentityCollisions(rules) {
+    const out = [];
+    for (const rule of rules ?? []) {
+        if (!rule || rule.sliceIdentity !== 'stars')
+            continue;
+        const groups = new Map();
+        const seen = new Map();
+        for (const raw of rule.sliceFolders ?? []) {
+            if (typeof raw !== 'string' || raw.length === 0)
+                continue;
+            const stem = starsIdentityStem(raw);
+            if (!stem)
+                continue;
+            const key = raw.split(/[/\\]/).filter((part) => part.length > 0).join('/').toLowerCase();
+            const groupSeen = seen.get(stem) ?? new Set();
+            if (groupSeen.has(key))
+                continue;
+            groupSeen.add(key);
+            seen.set(stem, groupSeen);
+            const paths = groups.get(stem) ?? [];
+            paths.push(raw);
+            groups.set(stem, paths);
         }
+        for (const [stem, paths] of groups) {
+            if (paths.length < 2)
+                continue;
+            out.push({
+                from: rule.from,
+                to: rule.to,
+                stem,
+                paths,
+                message: formatSliceIdentityCollision(rule.from, rule.to, paths, stem),
+            });
+        }
+    }
+    return out;
+}
+/** Last literal plus the stars that follow it. `**` never forms a stem. */
+function starsIdentityStem(raw) {
+    if (!isAnchoredSliceEntry(raw))
+        return undefined;
+    const segments = raw
+        .split(/[/\\]/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.toLowerCase());
+    let lastLiteral = -1;
+    for (let i = 0; i < segments.length; i += 1) {
+        const part = segments[i] ?? '';
+        if (part === '**')
+            return undefined;
+        if (part !== '*')
+            lastLiteral = i;
+    }
+    if (lastLiteral < 0)
+        return undefined;
+    const tail = segments.slice(lastLiteral);
+    if (tail.some((part, index) => index > 0 && part !== '*'))
+        return undefined;
+    return tail.join('/');
+}
+function formatSliceIdentityCollision(from, to, paths, stem) {
+    const named = paths.length === 2
+        ? `${paths[0]} and ${paths[1]}`
+        : `${paths.slice(0, -1).join(', ')}, and ${paths[paths.length - 1]}`;
+    return `${from} → ${to}: sliceIdentity "stars" gives one slice id to ${named}. They bind as ${stem}.`;
+}
+/** Bare names: leftmost folder, plus the next directory. Never the filename. */
+function bareSliceId(parts, names) {
+    if (names.size === 0)
+        return undefined;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        if (!names.has(parts[i].toLowerCase()))
+            continue;
+        if (i + 1 >= parts.length - 1)
+            continue;
+        return `${parts[i].toLowerCase()}/${parts[i + 1].toLowerCase()}`;
     }
     return undefined;
 }
@@ -279,6 +453,16 @@ function trimTrailingSlashes(value) {
 }
 /** Source folders a declared shared root may sit under without being named. */
 const SHARED_ROOT_SOURCE_PREFIXES = ['src', 'app'];
+/**
+ * Anchor at segment 0, or also at segment 1 when the path opens with `src/` or
+ * `app/` and the declaration does not itself start with that folder.
+ * Shared roots and starred slice prefixes share this offset.
+ */
+function anchorOffsets(parts, rootHead) {
+    const head = (parts[0] ?? '').toLowerCase();
+    const root = rootHead.toLowerCase();
+    return SHARED_ROOT_SOURCE_PREFIXES.includes(head) && root !== head ? [0, 1] : [0];
+}
 /** A root that would disable the wall wholesale is not a root. */
 function isBlanketRoot(raw) {
     const trimmed = trimTrailingSlashes(raw.replace(/^[./]+/, ''));
@@ -287,7 +471,7 @@ function isBlanketRoot(raw) {
 /**
  * Is `relPath` under one of the roots the rule declares shared on purpose?
  *
- * **Anchored**, unlike `sliceIdForPath`: the root must start the repo-relative
+ * **Anchored**: the root must start the repo-relative
  * path, optionally after a single conventional source folder, so `ui` covers
  * `ui/button.tsx` and `src/ui/button.tsx` but NOT `modules/a/ui/x.tsx` — an
  * unanchored root would exempt a whole tree the author never declared. Deeper
@@ -317,9 +501,7 @@ export function pathUnderSharedRoot(relPath, sharedRoots) {
         const root = normalizeSegments(raw);
         if (root.length === 0)
             continue;
-        // Anchor at segment 0, or at segment 1 when the path opens with a source
-        // folder the root does not itself name.
-        const offsets = SHARED_ROOT_SOURCE_PREFIXES.includes(parts[0]) && root[0] !== parts[0] ? [0, 1] : [0];
+        const offsets = anchorOffsets(parts, root[0] ?? '');
         for (const offset of offsets) {
             if (offset + root.length > parts.length)
                 continue;
@@ -364,7 +546,8 @@ export function crossSliceEdgeAllowed(allowedCrossSlice, fromSlice, toSlice) {
  * cross-slice edge, is the repo telling us its design, so it is no longer
  * "unclassifiable". Order: no fromPath → no slice folders → intent (no toPath):
  * shared-root allow / slice fail-closed → a side that is neither in a slice nor
- * declared shared → same slice → declared cross edge → deny.
+ * declared shared → shared root importing a slice (only when the rule denies
+ * that hop) → same slice → declared cross edge → deny.
  *
  * Intent/event names are not files. Callers pass fromPath only and must not
  * invent a toPath (that would mis-slice). A declared shared root is classified
@@ -386,6 +569,14 @@ export function peerIsolationDecision(input) {
     const toClassified = Boolean(input.toSlice) || input.toShared === true;
     if (!fromClassified || !toClassified)
         return { denied: true, reason: 'unclassifiable-path' };
+    // Shared roots are a sink. The hop is allowed unless the rule opts in.
+    // allowedCrossSlice does not excuse it: this is not a slice-to-slice edge.
+    if (input.sharedImportsSlice === 'deny' &&
+        input.fromShared === true &&
+        Boolean(input.toSlice) &&
+        !input.fromSlice) {
+        return { denied: true, reason: 'shared-imports-slice' };
+    }
     // At least one side is declared shared (and carries no slice id): the repo
     // said this code belongs to no slice, so there is no cross-slice edge here.
     if (!input.fromSlice || !input.toSlice)
@@ -416,6 +607,8 @@ export function peerIsolationDenyExplanation(reason, context) {
     switch (reason) {
         case 'cross-slice':
             return `cross-slice edge ${context.fromSlice ?? '?'} → ${context.toSlice ?? '?'}. Extract the shared code, use events/ports across slices, or declare the edge in the rule's allowedCrossSlice.`;
+        case 'shared-imports-slice':
+            return `shared root imports slice ${context.toSlice ?? '?'} (${context.fromPath ?? '?'} → ${context.toPath ?? '?'}). The wall is direct-only.`;
         case 'unclassifiable-path': {
             const unplaced = [
                 context.fromSlice ? undefined : context.fromPath,
@@ -463,8 +656,10 @@ export function findDeniedEdgeDecision(rules, from, to, options) {
             const fromPath = options?.fromPath;
             const toPath = options?.toPath;
             const folders = resolveSliceFolders(rule, from, options?.layers);
-            const fromSlice = fromPath ? sliceIdForPath(fromPath, folders) : undefined;
-            const toSlice = toPath ? sliceIdForPath(toPath, folders) : undefined;
+            const fromSlice = fromPath
+                ? sliceIdForPath(fromPath, folders, rule.sliceIdentity)
+                : undefined;
+            const toSlice = toPath ? sliceIdForPath(toPath, folders, rule.sliceIdentity) : undefined;
             const decision = peerIsolationDecision({
                 fromPath,
                 toPath,
@@ -474,6 +669,7 @@ export function findDeniedEdgeDecision(rules, from, to, options) {
                 fromShared: !fromSlice && pathUnderSharedRoot(fromPath, rule.sharedRoots),
                 toShared: !toSlice && pathUnderSharedRoot(toPath, rule.sharedRoots),
                 crossSliceAllowed: crossSliceEdgeAllowed(rule.allowedCrossSlice, fromSlice, toSlice),
+                sharedImportsSlice: rule.sharedImportsSlice,
             });
             if (decision.denied) {
                 return { rule, peerIsolationReason: decision.reason, fromSlice, toSlice };
@@ -487,6 +683,34 @@ export function findDeniedEdgeDecision(rules, from, to, options) {
     }
     return undefined;
 }
+/**
+ * Shared-root → slice edges the check still allows. Listed so a green run
+ * says the wall is direct-only. When the rule sets `sharedImportsSlice: "deny"`
+ * the same hop is a violation instead, so it is not listed twice.
+ */
+export function findSharedImportsSliceBridge(rules, from, to, options) {
+    const fromPath = options?.fromPath;
+    const toPath = options?.toPath;
+    if (!fromPath || !toPath)
+        return undefined;
+    for (const rule of rules ?? []) {
+        if (rule.from !== from || rule.to !== to)
+            continue;
+        if (rule.allowed !== false || !rule.peerIsolation)
+            continue;
+        if (rule.sharedImportsSlice === 'deny')
+            continue;
+        const folders = resolveSliceFolders(rule, from, options?.layers);
+        const fromSlice = sliceIdForPath(fromPath, folders, rule.sliceIdentity);
+        const toSlice = sliceIdForPath(toPath, folders, rule.sliceIdentity);
+        if (fromSlice || !toSlice)
+            continue;
+        if (!pathUnderSharedRoot(fromPath, rule.sharedRoots))
+            continue;
+        return { fromPath, toPath, toSlice };
+    }
+    return undefined;
+}
 export function isEdgeDenied(rules, from, to, options) {
     return findDeniedEdgeRule(rules, from, to, options) !== undefined;
 }

package/bin/ark.mjs

@@ -26,11 +26,13 @@ import {
   applyStartPreview,
   emitStartSetupBudgetRefuse,
   evaluateStartSetupBudgetGate,
-  formatStartPackageInstallFailure,
   planStart,
   renderStartPreview,
-  runStartPackageInstall,
 } 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';
@@ -509,6 +511,7 @@ async function start(args) {
               exitStatus: install.status,
               installCommand,
               hostOutput: `${install.stdout}\n${install.stderr}`,
+              packageVersion: cliVersion(),
             })
           );
           return install.status;
@@ -584,6 +587,7 @@ async function start(args) {
               exitStatus: installStatus,
               installCommand: `${command} ${commandArgs.join(' ')}`,
               hostOutput,
+              packageVersion: cliVersion(),
             })
           );
         }