@haystackeditor/cli 0.15.25 → 0.15.27

package/dist/commands/cloud-verifier-behaviors.d.ts

@@ -0,0 +1,27 @@
+export declare const MAX_BEHAVIOR_ARTIFACT_BYTES: number;
+type RecordValue = Record<string, any>;
+export interface BehaviorValidationIssue {
+    path: string;
+    message: string;
+}
+export interface BehaviorValidationResult {
+    version: 'haystack-behavior-validation-v1';
+    status: 'valid' | 'invalid';
+    issues: BehaviorValidationIssue[];
+    summary: {
+        actions: number;
+        boundaries: number;
+    };
+}
+export declare function derivedBehaviorActionId(repository: string, trigger: RecordValue): string;
+export declare function derivedBehaviorSymbolId(repository: string, sourcePath: string, qualifiedName: string): string;
+export declare function derivedBehaviorBoundaryId(repository: string, kind: string, identityKey: string): string;
+export declare function validateBehaviorArtifact(value: RecordValue, references: {
+    universe: RecordValue;
+    evidence: RecordValue;
+}): BehaviorValidationResult;
+export declare function resolveBehaviorArtifactRoot(gitRoot: string | null, currentDirectory?: string): string;
+export declare function cloudVerifierBehaviorsValidateCommand(options: {
+    json?: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/cloud-verifier-behaviors.js

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { parseDocument } from 'yaml';
+import { findGitRoot } from '../utils/hooks.js';
+// Keep behavior validation on the same bounded artifact envelope as universe
+// validation. Large maps must not need a lossy reference projection merely to
+// validate their exact interface and evidence joins.
+export const MAX_BEHAVIOR_ARTIFACT_BYTES = 32 * 1024 * 1024;
+const GIT_COMMIT = /^[0-9a-f]{40}$/;
+const STABLE_UNIVERSE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const REPOSITORY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+const RUNTIME_ID = /^(?:action|symbol|boundary)-[0-9a-f]{24}$/;
+const BOUNDARY_KINDS = new Set(['response', 'state', 'event', 'external', 'ui', 'cli', 'job']);
+const TRIGGER_KINDS = new Set(['http', 'event', 'job', 'cli', 'ui']);
+function stableIdentity(prefix, parts) {
+    const framed = parts.map(part => `${Buffer.byteLength(part, 'utf8')}:${part}`).join('|');
+    return `${prefix}-${createHash('sha256').update(framed).digest('hex').slice(0, 24)}`;
+}
+function normalizeRepository(repository) {
+    if (!REPOSITORY.test(repository))
+        throw new Error('must be a canonical owner/repository identity');
+    return repository.toLowerCase();
+}
+function normalizePath(sourcePath) {
+    const normalized = sourcePath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    if (!normalized || normalized.split('/').some(part => !part || part === '..')) {
+        throw new Error('must be a normalized repository-relative source path');
+    }
+    return normalized;
+}
+export function derivedBehaviorActionId(repository, trigger) {
+    let identity;
+    if (trigger?.kind === 'http') {
+        if (typeof trigger.method !== 'string' || typeof trigger.route_template !== 'string') {
+            throw new Error('HTTP trigger requires method and route_template');
+        }
+        identity = `${trigger.method.toUpperCase()} ${trigger.route_template}`;
+    }
+    else if (trigger?.kind === 'event') {
+        if (typeof trigger.channel_identity !== 'string' || typeof trigger.event_type !== 'string') {
+            throw new Error('event trigger requires channel_identity and event_type');
+        }
+        identity = `${trigger.channel_identity}\0${trigger.event_type}`;
+    }
+    else if (trigger?.kind === 'job')
+        identity = trigger.job_identity;
+    else if (trigger?.kind === 'cli')
+        identity = trigger.command_identity;
+    else if (trigger?.kind === 'ui')
+        identity = trigger.action_identity;
+    else
+        throw new Error('trigger kind must be http, event, job, cli, or ui');
+    if (typeof identity !== 'string' || !identity.trim())
+        throw new Error('trigger identity must be non-empty');
+    return stableIdentity('action', [normalizeRepository(repository), trigger.kind, identity]);
+}
+export function derivedBehaviorSymbolId(repository, sourcePath, qualifiedName) {
+    if (typeof qualifiedName !== 'string' || !qualifiedName.trim())
+        throw new Error('qualified_name must be non-empty');
+    return stableIdentity('symbol', [normalizeRepository(repository), normalizePath(sourcePath), qualifiedName.trim()]);
+}
+export function derivedBehaviorBoundaryId(repository, kind, identityKey) {
+    if (!BOUNDARY_KINDS.has(kind))
+        throw new Error('boundary kind is unsupported');
+    if (typeof identityKey !== 'string' || !identityKey.trim())
+        throw new Error('identity_key must be non-empty');
+    return stableIdentity('boundary', [normalizeRepository(repository), kind, identityKey.trim()]);
+}
+function parseYaml(text, name) {
+    const document = parseDocument(text, { prettyErrors: false });
+    if (document.errors.length)
+        throw new Error(`${name} is malformed YAML: ${document.errors[0].message}`);
+    const value = document.toJS({ maxAliasCount: 50 });
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${name} must contain a mapping`);
+    return value;
+}
+export function validateBehaviorArtifact(value, references) {
+    const issues = [];
+    const fail = (path, message) => issues.push({ path, message });
+    if (value?.version !== 1)
+        fail('version', 'must equal 1');
+    if (value?.schema_version !== 'haystack-behavior-map-v1') {
+        fail('schema_version', 'must equal haystack-behavior-map-v1');
+    }
+    let repository = '';
+    try {
+        repository = normalizeRepository(value?.repository);
+    }
+    catch (error) {
+        fail('repository', error.message);
+    }
+    if (!GIT_COMMIT.test(value?.source_commit || ''))
+        fail('source_commit', 'must be an exact Git commit');
+    const universeCommit = references.universe?.map_revision?.source_commit;
+    if (value?.source_commit !== universeCommit)
+        fail('source_commit', 'must exactly match universe.yml map_revision.source_commit');
+    const interfaceIds = new Set((Array.isArray(references.universe?.interfaces)
+        ? references.universe.interfaces : []).map((item) => item?.id));
+    const evidenceIds = new Set((Array.isArray(references.evidence?.evidence)
+        ? references.evidence.evidence : []).map((item) => item?.id));
+    if (!Array.isArray(value?.actions) || value.actions.length === 0) {
+        fail('actions', 'must contain at least one meaningful customer action');
+        return { version: 'haystack-behavior-validation-v1', status: 'invalid', issues, summary: { actions: 0, boundaries: 0 } };
+    }
+    const actionIds = new Set();
+    const triggerIds = new Set();
+    let boundaryCount = 0;
+    for (const [index, action] of value.actions.entries()) {
+        const path = `actions[${index}]`;
+        if (!action || typeof action !== 'object' || Array.isArray(action)) {
+            fail(path, 'must be a mapping');
+            continue;
+        }
+        let expectedAction = '';
+        try {
+            expectedAction = derivedBehaviorActionId(repository || value.repository, action.trigger);
+        }
+        catch (error) {
+            fail(`${path}.trigger`, error.message);
+        }
+        if (!RUNTIME_ID.test(action.id || '') || action.id !== expectedAction)
+            fail(`${path}.id`, `must equal derived exact id ${expectedAction}`);
+        if (actionIds.has(action.id))
+            fail(`${path}.id`, 'must be unique');
+        actionIds.add(action.id);
+        if (!TRIGGER_KINDS.has(action.trigger?.kind))
+            fail(`${path}.trigger.kind`, 'is unsupported');
+        if (triggerIds.has(expectedAction))
+            fail(`${path}.trigger`, 'duplicates another structured trigger');
+        triggerIds.add(expectedAction);
+        if (!STABLE_UNIVERSE_ID.test(action.interface_id || '') || !interfaceIds.has(action.interface_id)) {
+            fail(`${path}.interface_id`, 'must reference an exact universe.yml interface id');
+        }
+        let expectedSymbol = '';
+        try {
+            expectedSymbol = derivedBehaviorSymbolId(repository || value.repository, action.handler?.source_path, action.handler?.qualified_name);
+        }
+        catch (error) {
+            fail(`${path}.handler`, error.message);
+        }
+        if (action.handler?.symbol_id !== expectedSymbol)
+            fail(`${path}.handler.symbol_id`, `must equal derived exact id ${expectedSymbol}`);
+        if (!Array.isArray(action.observable_boundaries) || action.observable_boundaries.length === 0) {
+            fail(`${path}.observable_boundaries`, 'must contain a customer-relevant boundary');
+        }
+        else {
+            const boundaryIds = new Set();
+            for (const [boundaryIndex, boundary] of action.observable_boundaries.entries()) {
+                boundaryCount += 1;
+                const boundaryPath = `${path}.observable_boundaries[${boundaryIndex}]`;
+                let expectedBoundary = '';
+                try {
+                    expectedBoundary = derivedBehaviorBoundaryId(repository || value.repository, boundary?.kind, boundary?.identity_key);
+                }
+                catch (error) {
+                    fail(boundaryPath, error.message);
+                }
+                if (boundary?.id !== expectedBoundary)
+                    fail(`${boundaryPath}.id`, `must equal derived exact id ${expectedBoundary}`);
+                if (boundaryIds.has(boundary?.id))
+                    fail(`${boundaryPath}.id`, 'must be unique in the action');
+                boundaryIds.add(boundary?.id);
+            }
+        }
+        if (!Array.isArray(action.evidence_ids) || action.evidence_ids.length === 0) {
+            fail(`${path}.evidence_ids`, 'must contain exact repository evidence');
+        }
+        else {
+            for (const evidenceId of action.evidence_ids) {
+                if (!evidenceIds.has(evidenceId))
+                    fail(`${path}.evidence_ids`, `references unknown evidence id ${String(evidenceId)}`);
+            }
+        }
+    }
+    return {
+        version: 'haystack-behavior-validation-v1',
+        status: issues.length ? 'invalid' : 'valid',
+        issues,
+        summary: { actions: value.actions.length, boundaries: boundaryCount },
+    };
+}
+function readArtifact(root, name) {
+    const path = join(root, '.haystack', 'cloud-verifier', name);
+    const metadata = lstatSync(path, { throwIfNoEntry: false });
+    if (!metadata || !metadata.isFile() || metadata.isSymbolicLink())
+        throw new Error(`${name} must be a regular non-symlink file`);
+    if (metadata.size > MAX_BEHAVIOR_ARTIFACT_BYTES) {
+        throw new Error(`${name} exceeds ${MAX_BEHAVIOR_ARTIFACT_BYTES} bytes`);
+    }
+    return readFileSync(path, 'utf8');
+}
+export function resolveBehaviorArtifactRoot(gitRoot, currentDirectory = process.cwd()) {
+    return gitRoot ?? currentDirectory;
+}
+export async function cloudVerifierBehaviorsValidateCommand(options) {
+    // Source-only evaluation archives deliberately omit Git metadata. The
+    // behavior validator only reads verifier artifacts, so current-directory
+    // fallback is both sufficient and consistent with validate-universe.
+    const root = resolveBehaviorArtifactRoot(findGitRoot());
+    const value = parseYaml(readArtifact(root, 'behaviors.yml'), 'behaviors.yml');
+    const universe = parseYaml(readArtifact(root, 'universe.yml'), 'universe.yml');
+    const evidence = parseYaml(readArtifact(root, 'evidence.yml'), 'evidence.yml');
+    const result = validateBehaviorArtifact(value, { universe, evidence });
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else if (result.status === 'valid') {
+        console.log(chalk.green(`Behavior map valid: ${result.summary.actions} actions, ${result.summary.boundaries} boundaries`));
+    }
+    else {
+        for (const issue of result.issues)
+            console.error(chalk.red(`behaviors.yml:${issue.path}: ${issue.message}`));
+    }
+    if (result.status !== 'valid')
+        process.exitCode = 1;
+}

package/dist/commands/cloud-verifier-data-store-census.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Data-store census.
+ *
+ * The one job the Cloud Verifier needs from a repository map: what data stores
+ * does this application use, so we can clone each one into a replica. Not
+ * processes, not API calls, not code structure — the databases, caches, object
+ * stores, search indexes, and queues that hold state a test must run against.
+ *
+ * Four source signals, strongest first:
+ *   1. a service image in a compose/k8s manifest (`image: postgres:16`) — a
+ *      store instance the app is wired to run beside, the surest signal;
+ *   2. a connection URL scheme or conventional env var (`postgres://`,
+ *      `REDIS_URL`) — an instance named in config;
+ *   3. a config declaration that names a store without an image, library, or URL
+ *      (Django `ENGINE`, PHP PDO, Laravel `DB_CONNECTION`, Rails `adapter:`);
+ *   4. a client library in a dependency manifest (`pg`, `redis`, `mongoose`) —
+ *      the app talks to that engine.
+ *
+ * Signals are folded per engine into one data store, with the evidence, a
+ * confidence, and how to reproduce it. Everything here is a general convention,
+ * never a repository-specific constant.
+ */
+export type DataStoreCategory = 'relational-database' | 'document-database' | 'key-value-store' | 'wide-column-database' | 'columnar-database' | 'graph-database' | 'vector-database' | 'object-storage' | 'search-index' | 'message-queue' | 'time-series-database' | 'embedded-database';
+export interface DataStoreSignal {
+    kind: 'service-image' | 'client-library' | 'connection-url' | 'config-declaration';
+    value: string;
+    path: string;
+}
+export type DataStoreConfidence = 'running' | 'configured' | 'library';
+export interface DataStore {
+    engine: string;
+    category: DataStoreCategory;
+    clone_strategy: string;
+    confidence: DataStoreConfidence;
+    signals: DataStoreSignal[];
+}
+export interface DataStoreCensusInput {
+    path: string;
+    lowerName: string;
+    text: string;
+}
+/**
+ * Fold a stream of manifest/compose/config files into the distinct data stores
+ * the application uses. `inputs` is every scanned text file with its lowercased
+ * basename; the detector reads only the manifests and configs it recognizes.
+ */
+export declare function detectDataStores(inputs: DataStoreCensusInput[]): DataStore[];