@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/mesh/preview-freshness.ts

@@ -0,0 +1,163 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export type PreviewFreshnessStatus = 'fresh' | 'stale' | 'unknown' | 'not_configured';
+
+export interface PreviewFreshness {
+    status: PreviewFreshnessStatus;
+    lastPreviewCommit: string | null;
+    currentMainCommit: string | null;
+    currentMainCommitSource: 'origin/main' | 'HEAD' | 'unknown';
+    recordPath: string;
+    lastDeployedAt?: string;
+    lastTarget?: string;
+    previewVersion?: string;
+    targets: Record<'npm' | 'server' | 'web', {
+        commit: string | null;
+        deployedAt?: string;
+        status: PreviewFreshnessStatus;
+    }>;
+    nextAction: string;
+}
+
+const PREVIEW_DEPLOY_RECORD = '.adhdev/preview-deploy.json';
+
+// Repo-relative driver scripts that indicate this repository actually ships the
+// preview-deploy pipeline. Presence of any one of these (or the deploy record,
+// or a `deploy:preview` npm script) means the private release-pipeline guidance
+// carried by buildPreviewFreshness is relevant here. In every other repo the
+// pipeline is not configured and the guidance must NOT leak (F15).
+const PREVIEW_PIPELINE_SCRIPTS = [
+    'scripts/preview-freshness.mjs',
+    'scripts/smoke-preview-web.mjs',
+    'scripts/deploy-preview-local.mjs',
+] as const;
+
+function hasDeployPreviewNpmScript(repoRoot: string): boolean {
+    const pkgPath = resolve(repoRoot, 'package.json');
+    if (!existsSync(pkgPath)) return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, unknown> };
+        return typeof pkg?.scripts?.['deploy:preview'] === 'string';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Gate: does this repository actually configure the preview-deploy pipeline?
+ *
+ * The preview-freshness surface embeds this project's private release-pipeline
+ * instructions (`npm run deploy:preview`, smoke preview, …). Those are only
+ * meaningful in a repo that ships the pipeline. An external repo joined to a
+ * mesh must not have that guidance leak into its coordinator prompt, so this
+ * gate keeps the surface off unless a concrete pipeline artifact is present.
+ */
+export function isPreviewPipelineConfigured(repoRoot: string): boolean {
+    // Strongest signal: the repo has produced a preview-deploy record before.
+    if (existsSync(resolve(repoRoot, PREVIEW_DEPLOY_RECORD))) return true;
+    // Otherwise the pipeline's own driver scripts are enough.
+    if (PREVIEW_PIPELINE_SCRIPTS.some((rel) => existsSync(resolve(repoRoot, rel)))) return true;
+    // Or the `deploy:preview` npm script that fronts the pipeline.
+    return hasDeployPreviewNpmScript(repoRoot);
+}
+
+function runGit(repoRoot: string, args: readonly string[]): string {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).trim();
+    } catch {
+        return '';
+    }
+}
+
+function readRecord(repoRoot: string): Record<string, unknown> | null {
+    const path = resolve(repoRoot, PREVIEW_DEPLOY_RECORD);
+    if (!existsSync(path)) return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed as Record<string, unknown>
+            : null;
+    } catch {
+        return null;
+    }
+}
+
+function normalizeCommit(value: unknown): string | null {
+    return typeof value === 'string' && /^[0-9a-f]{7,40}$/i.test(value.trim())
+        ? value.trim()
+        : null;
+}
+
+function readTargetFreshness(record: Record<string, unknown> | null, currentCommit: string | null): PreviewFreshness['targets'] {
+    const targets = record?.targets && typeof record.targets === 'object' && !Array.isArray(record.targets)
+        ? record.targets as Record<string, unknown>
+        : {};
+    const result = {} as PreviewFreshness['targets'];
+    for (const targetName of ['npm', 'server', 'web'] as const) {
+        const targetRecord = targets[targetName] && typeof targets[targetName] === 'object' && !Array.isArray(targets[targetName])
+            ? targets[targetName] as Record<string, unknown>
+            : {};
+        const commit = normalizeCommit(targetRecord.commit);
+        result[targetName] = {
+            commit,
+            deployedAt: typeof targetRecord.deployedAt === 'string' ? targetRecord.deployedAt : undefined,
+            status: commit && currentCommit ? (commit === currentCommit ? 'fresh' : 'stale') : 'unknown',
+        };
+    }
+    return result;
+}
+
+function readCurrentMainCommit(repoRoot: string): Pick<PreviewFreshness, 'currentMainCommit' | 'currentMainCommitSource'> {
+    const originMain = runGit(repoRoot, ['rev-parse', '--verify', 'origin/main^{commit}']);
+    if (originMain) {
+        return { currentMainCommit: originMain, currentMainCommitSource: 'origin/main' };
+    }
+    const head = runGit(repoRoot, ['rev-parse', '--verify', 'HEAD']);
+    if (head) {
+        return { currentMainCommit: head, currentMainCommitSource: 'HEAD' };
+    }
+    return { currentMainCommit: null, currentMainCommitSource: 'unknown' };
+}
+
+export function buildPreviewFreshness(repoRoot: string): PreviewFreshness | null {
+    // F15 gate: only surface preview-freshness (and its private pipeline
+    // guidance) in repos that actually configure the preview-deploy pipeline.
+    // Unconfigured repos return null so the caller omits the field entirely.
+    if (!isPreviewPipelineConfigured(repoRoot)) return null;
+
+    const current = readCurrentMainCommit(repoRoot);
+    const record = readRecord(repoRoot);
+    const lastPreviewCommit = normalizeCommit(record?.lastPreviewCommit);
+    const targets = readTargetFreshness(record, current.currentMainCommit);
+    let status: PreviewFreshnessStatus = 'unknown';
+    let nextAction = 'Run npm run deploy:preview from the current main commit, then smoke preview.';
+
+    if (lastPreviewCommit && current.currentMainCommit) {
+        status = lastPreviewCommit === current.currentMainCommit ? 'fresh' : 'stale';
+        nextAction = status === 'fresh'
+            ? 'No preview deploy action needed.'
+            : 'Run npm run deploy:preview from origin/main, then smoke preview.';
+    } else if (!current.currentMainCommit) {
+        nextAction = 'Resolve the current main commit before judging preview freshness.';
+    }
+
+    return {
+        status,
+        lastPreviewCommit,
+        currentMainCommit: current.currentMainCommit,
+        currentMainCommitSource: current.currentMainCommitSource,
+        recordPath: PREVIEW_DEPLOY_RECORD,
+        lastDeployedAt: typeof record?.updatedAt === 'string' ? record.updatedAt : undefined,
+        lastTarget: typeof record?.target === 'string' ? record.target : undefined,
+        previewVersion: typeof record?.previewVersion === 'string' ? record.previewVersion : undefined,
+        targets,
+        nextAction,
+    };
+}

package/src/mesh/refine-config.ts

@@ -13,13 +13,36 @@ export interface RepoMeshRefineValidationCommandConfig {
     category?: MeshRefineValidationCategory;
     cwd?: string;
     timeoutMs?: number;
+    outputLimitBytes?: number;
     env?: Record<string, string>;
 }
 
 export interface RepoMeshRefineConfig {
     version: 1;
+    /**
+     * Narrow Refinery opt-in for monorepos with submodule gitlinks.
+     * When true, Refinery may non-force publish unreachable submodule gitlink
+     * commits to the submodule remote main branch after validation and
+     * patch-equivalence pass, then verify remote-main reachability.
+     */
+    allowAutoPublishSubmoduleMainCommits?: boolean;
     validation?: {
         required?: boolean;
+        /**
+         * M2-2 (v2): how Refinery sources its bootstrap stage.
+         *   'inherit' (default) — consume the worktree_bootstrap config/state:
+         *     skip when the node's bootstrap is 'ready' (staleInputs unchanged),
+         *     run the worktree_bootstrap definition when stale/never-ran.
+         *   'skip' — no bootstrap stage at all (validation commands run as-is).
+         */
+        bootstrap?: 'inherit' | 'skip';
+        /**
+         * DEPRECATED (M2-2): define bootstrap once in
+         * .adhdev/worktree_bootstrap.json instead. Still honored when no
+         * worktree_bootstrap config exists, with a deprecation warning; when
+         * both exist the worktree_bootstrap config wins.
+         */
+        bootstrapCommands?: RepoMeshRefineValidationCommandConfig[];
         commands?: RepoMeshRefineValidationCommandConfig[];
     };
 }
@@ -32,6 +55,7 @@ export interface MeshRefineValidationCommandPlan {
     source: string;
     cwd?: string;
     timeoutMs?: number;
+    outputLimitBytes?: number;
     env?: Record<string, string>;
 }
 
@@ -46,8 +70,13 @@ export interface MeshRefineConfigLoadResult {
 export interface MeshRefineValidationPlan {
     source: string;
     sourceType: MeshRefineConfigLoadResult['sourceType'];
+    /** M2-2: how the bootstrap stage is sourced ('inherit' consumes worktree_bootstrap; 'skip' disables it). */
+    bootstrapMode: 'inherit' | 'skip';
+    bootstrapCommands: MeshRefineValidationCommandPlan[];
     commands: MeshRefineValidationCommandPlan[];
     rejectedCommands: Array<Record<string, unknown>>;
+    /** M2-2: deprecation notices (e.g. validation.bootstrapCommands present). */
+    deprecationWarnings: string[];
     suggestions: RepoMeshRefineValidationCommandConfig[];
     suggestedConfig?: RepoMeshRefineConfig;
     unavailableReason?: string;
@@ -73,11 +102,21 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
     required: ['version'],
     properties: {
         version: { const: 1 },
+        allowAutoPublishSubmoduleMainCommits: {
+            type: 'boolean',
+            default: false,
+            description: 'When true, Refinery may non-force publish submodule gitlink commits referenced by the refined root tree to each submodule origin/main after validation and patch-equivalence pass, then verify reachability.',
+        },
         validation: {
             type: 'object',
             additionalProperties: false,
             properties: {
                 required: { type: 'boolean', default: true },
+                bootstrap: {
+                    enum: ['inherit', 'skip'],
+                    default: 'inherit',
+                    description: "M2-2 (v2): 'inherit' consumes the worktree_bootstrap config/state (skip when ready, rerun when stale); 'skip' disables the bootstrap stage entirely.",
+                },
                 commands: {
                     type: 'array',
                     minItems: 1,
@@ -92,6 +131,26 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
                             category: { enum: [...MESH_REFINE_VALIDATION_CATEGORIES, 'custom'] },
                             cwd: { type: 'string' },
                             timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
+                            outputLimitBytes: { type: 'number', minimum: 1024, maximum: 1048576 },
+                            env: { type: 'object', additionalProperties: { type: 'string' } },
+                        },
+                    },
+                },
+                bootstrapCommands: {
+                    type: 'array',
+                    maxItems: 4,
+                    description: 'DEPRECATED: define bootstrap once in .adhdev/worktree_bootstrap.json. Honored only when no worktree_bootstrap config exists (with a deprecation warning); worktree_bootstrap wins when both exist.',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['command'],
+                        properties: {
+                            command: { type: 'string', minLength: 1 },
+                            args: { type: 'array', items: { type: 'string' } },
+                            category: { enum: [...MESH_REFINE_VALIDATION_CATEGORIES, 'custom'] },
+                            cwd: { type: 'string' },
+                            timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
+                            outputLimitBytes: { type: 'number', minimum: 1024, maximum: 1048576 },
                             env: { type: 'object', additionalProperties: { type: 'string' } },
                         },
                     },
@@ -101,19 +160,39 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
     },
 } as const;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+export function isMeshConfigRecord(value: unknown): value is Record<string, unknown> {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
 
-function tokenizeCommandString(command: string): string[] | null {
+// True shell metacharacters — never allowed anywhere in a config command, on
+// any platform. Note: backslash is deliberately NOT in this set; it is handled
+// separately (allowed only in the win32 executable token).
+const SHELL_METACHAR_RE = /[;&|<>`$\n\r'"]/;
+// Per-token allowlist for argument tokens and non-win32 executable tokens.
+const SAFE_TOKEN_RE = /^[A-Za-z0-9_@./:=+-]+$/;
+// Executable token on win32: same as SAFE_TOKEN_RE but also permits backslash so
+// an absolute path like C:\Users\me\AppData\Roaming\npm\npm.cmd is accepted.
+const SAFE_WIN32_EXEC_TOKEN_RE = /^[A-Za-z0-9_@./:=+\\-]+$/;
+
+export function tokenizeCommandString(command: string): string[] | null {
     const trimmed = command.trim();
     if (!trimmed) return null;
     // Explicit config may name any executable, but the Refinery never invokes a shell.
     // Reject shell syntax, quotes and substitutions so config cannot smuggle a compound command.
-    if (/[;&|<>`$\\\n\r'\"]/.test(trimmed)) return null;
+    // Backslash is the one exception (handled per-token below): rejecting it here
+    // would block legitimate win32 absolute .cmd paths, but it is never a shell
+    // metacharacter in the no-shell execFile boundary we run under.
+    if (SHELL_METACHAR_RE.test(trimmed)) return null;
     const tokens = trimmed.split(/\s+/).filter(Boolean);
     if (!tokens.length) return null;
-    if (tokens.some(token => !/^[A-Za-z0-9_@./:=+-]+$/.test(token))) return null;
+    const isWin32 = process.platform === 'win32';
+    for (let i = 0; i < tokens.length; i++) {
+        // Backslash is permitted ONLY in the executable (first) token, ONLY on
+        // win32. Every other token (and all tokens off win32) uses the strict
+        // allowlist with no backslash.
+        const re = (isWin32 && i === 0) ? SAFE_WIN32_EXEC_TOKEN_RE : SAFE_TOKEN_RE;
+        if (!re.test(tokens[i])) return null;
+    }
     return tokens;
 }
 
@@ -123,8 +202,8 @@ function validateCategory(value: unknown): MeshRefineValidationCategory | 'custo
         : 'custom';
 }
 
-function normalizeCommandConfig(entry: unknown, source: string): { command?: MeshRefineValidationCommandPlan; rejected?: Record<string, unknown> } {
-    if (!isRecord(entry) || typeof entry.command !== 'string') {
+export function normalizeMeshCommandConfig(entry: unknown, source: string): { command?: MeshRefineValidationCommandPlan; rejected?: Record<string, unknown> } {
+    if (!isMeshConfigRecord(entry) || typeof entry.command !== 'string') {
         return { rejected: { source, reason: 'validation command must be an object with a command string' } };
     }
 
@@ -154,7 +233,10 @@ function normalizeCommandConfig(entry: unknown, source: string): { command?: Mes
     if (entry.timeoutMs !== undefined && (typeof entry.timeoutMs !== 'number' || !Number.isFinite(entry.timeoutMs) || entry.timeoutMs < 1000 || entry.timeoutMs > 600000)) {
         return { rejected: { source, command: commandText, reason: 'timeoutMs must be between 1000 and 600000' } };
     }
-    if (entry.env !== undefined && (!isRecord(entry.env) || !Object.values(entry.env).every(value => typeof value === 'string'))) {
+    if (entry.outputLimitBytes !== undefined && (typeof entry.outputLimitBytes !== 'number' || !Number.isFinite(entry.outputLimitBytes) || entry.outputLimitBytes < 1024 || entry.outputLimitBytes > 1048576)) {
+        return { rejected: { source, command: commandText, reason: 'outputLimitBytes must be between 1024 and 1048576' } };
+    }
+    if (entry.env !== undefined && (!isMeshConfigRecord(entry.env) || !Object.values(entry.env).every(value => typeof value === 'string'))) {
         return { rejected: { source, command: commandText, reason: 'env must be an object of string values' } };
     }
 
@@ -167,31 +249,60 @@ function normalizeCommandConfig(entry: unknown, source: string): { command?: Mes
             source,
             ...(typeof entry.cwd === 'string' && entry.cwd.trim() ? { cwd: entry.cwd.trim() } : {}),
             ...(typeof entry.timeoutMs === 'number' ? { timeoutMs: entry.timeoutMs } : {}),
-            ...(isRecord(entry.env) ? { env: entry.env as Record<string, string> } : {}),
+            ...(typeof entry.outputLimitBytes === 'number' ? { outputLimitBytes: entry.outputLimitBytes } : {}),
+            ...(isMeshConfigRecord(entry.env) ? { env: entry.env as Record<string, string> } : {}),
         },
     };
 }
 
-export function validateMeshRefineConfig(config: unknown, source = 'inline'): { valid: boolean; errors: string[]; commands: MeshRefineValidationCommandPlan[]; rejectedCommands: Array<Record<string, unknown>> } {
+const isRecord = isMeshConfigRecord;
+
+export function validateMeshRefineConfig(config: unknown, source = 'inline'): { valid: boolean; errors: string[]; bootstrapCommands: MeshRefineValidationCommandPlan[]; commands: MeshRefineValidationCommandPlan[]; rejectedCommands: Array<Record<string, unknown>>; bootstrapMode: 'inherit' | 'skip'; deprecationWarnings: string[] } {
     const errors: string[] = [];
+    const bootstrapCommands: MeshRefineValidationCommandPlan[] = [];
     const commands: MeshRefineValidationCommandPlan[] = [];
     const rejectedCommands: Array<Record<string, unknown>> = [];
+    const deprecationWarnings: string[] = [];
+    let bootstrapMode: 'inherit' | 'skip' = 'inherit';
 
-    if (!isRecord(config)) return { valid: false, errors: ['config must be an object'], commands, rejectedCommands };
+    if (!isRecord(config)) return { valid: false, errors: ['config must be an object'], bootstrapCommands, commands, rejectedCommands, bootstrapMode, deprecationWarnings };
     if (config.version !== 1) errors.push('version must be 1');
+    if (config.allowAutoPublishSubmoduleMainCommits !== undefined && typeof config.allowAutoPublishSubmoduleMainCommits !== 'boolean') {
+        errors.push('allowAutoPublishSubmoduleMainCommits must be a boolean when provided');
+    }
     const validation = config.validation;
     if (validation !== undefined && !isRecord(validation)) errors.push('validation must be an object');
+    const rawBootstrapMode = isRecord(validation) ? validation.bootstrap : undefined;
+    if (rawBootstrapMode !== undefined) {
+        if (rawBootstrapMode === 'inherit' || rawBootstrapMode === 'skip') {
+            bootstrapMode = rawBootstrapMode;
+        } else {
+            errors.push("validation.bootstrap must be 'inherit' or 'skip' when provided");
+        }
+    }
     const rawCommands = isRecord(validation) ? validation.commands : undefined;
+    const rawBootstrapCommands = isRecord(validation) ? validation.bootstrapCommands : undefined;
     if (rawCommands !== undefined && !Array.isArray(rawCommands)) errors.push('validation.commands must be an array');
+    if (rawBootstrapCommands !== undefined && !Array.isArray(rawBootstrapCommands)) errors.push('validation.bootstrapCommands must be an array');
+    if (Array.isArray(rawBootstrapCommands) && rawBootstrapCommands.length > 0) {
+        deprecationWarnings.push('validation.bootstrapCommands is deprecated: define bootstrap once in .adhdev/worktree_bootstrap.json. It still runs when no worktree_bootstrap config exists; when both exist the worktree_bootstrap config wins.');
+    }
+    if (Array.isArray(rawBootstrapCommands)) {
+        rawBootstrapCommands.forEach((entry, index) => {
+            const normalized = normalizeMeshCommandConfig(entry, `${source}:validation.bootstrapCommands[${index}]`);
+            if (normalized.command) bootstrapCommands.push(normalized.command);
+            if (normalized.rejected) rejectedCommands.push(normalized.rejected);
+        });
+    }
     if (Array.isArray(rawCommands)) {
         rawCommands.forEach((entry, index) => {
-            const normalized = normalizeCommandConfig(entry, `${source}:validation.commands[${index}]`);
+            const normalized = normalizeMeshCommandConfig(entry, `${source}:validation.commands[${index}]`);
             if (normalized.command) commands.push(normalized.command);
             if (normalized.rejected) rejectedCommands.push(normalized.rejected);
         });
     }
     if (rejectedCommands.length) errors.push('one or more validation commands are invalid');
-    return { valid: errors.length === 0, errors, commands, rejectedCommands };
+    return { valid: errors.length === 0, errors, bootstrapCommands, commands, rejectedCommands, bootstrapMode, deprecationWarnings };
 }
 
 function parseConfigText(path: string, text: string): unknown {
@@ -285,8 +396,11 @@ export function resolveMeshRefineValidationPlan(mesh: any, workspace: string): M
         return {
             source: loaded.source,
             sourceType: loaded.sourceType,
+            bootstrapMode: 'inherit',
+            bootstrapCommands: [],
             commands: [],
             rejectedCommands: loaded.error ? [{ source: loaded.source, reason: loaded.error }] : [],
+            deprecationWarnings: [],
             suggestions: suggestion.suggestions,
             suggestedConfig: suggestion.suggestedConfig,
             unavailableReason: loaded.error || 'validation_unavailable: repo mesh/refine config missing',
@@ -297,8 +411,11 @@ export function resolveMeshRefineValidationPlan(mesh: any, workspace: string): M
     return {
         source: loaded.path || loaded.source,
         sourceType: loaded.sourceType,
+        bootstrapMode: validation.bootstrapMode,
+        bootstrapCommands: validation.bootstrapCommands,
         commands: validation.commands,
         rejectedCommands: validation.rejectedCommands,
+        deprecationWarnings: validation.deprecationWarnings,
         suggestions: suggestion.suggestions,
         suggestedConfig: suggestion.suggestedConfig,
         unavailableReason: validation.commands.length ? undefined : 'validation_unavailable: repo mesh/refine config has no validation.commands',