@haystackeditor/cli 0.15.26 → 0.15.27

package/dist/commands/schema-cmd.js

@@ -14,8 +14,40 @@ import { SCHEMA_VERSIONS } from '../schema.js';
 // Derive valid schema names from the registry so adding a new schema only
 // requires editing SCHEMA_VERSIONS (PR008 — single source of truth).
 const VALID = Object.keys(SCHEMA_VERSIONS);
+/**
+ * Commands whose *input* payload callers reasonably expect to find here.
+ *
+ * `haystack schema` publishes `--json` output schemas only. Answering a request
+ * for one of these with a bare "Unknown schema" sends the caller hunting for a
+ * schema that was never on this surface, so name the real contract instead.
+ */
+const INPUT_PAYLOAD_CONTRACTS = {
+    'scaffold-provisional-universe': {
+        schemaName: 'cloud-verifier',
+        contract: 'the map-cloud-verifier-universe skill, references/output-contract.md '
+            + '("Scope and production authority")',
+    },
+    'validate-universe': {
+        schemaName: 'cloud-verifier',
+        contract: 'the map-cloud-verifier-universe skill, references/output-contract.md',
+    },
+};
 export function schemaCommand(name) {
     if (!VALID.includes(name)) {
+        const known = INPUT_PAYLOAD_CONTRACTS[name];
+        if (known) {
+            console.error(chalk.red(`No published schema for "${name}".`)
+                + `\n\n${chalk.bold('haystack schema')} publishes JSON Schemas for command `
+                + `${chalk.bold('--json output')} only; "${name}" takes a strict ${chalk.bold('--input')} `
+                + `payload, whose contract is not published here.`
+                + `\n\nInput contract:  ${known.contract}`
+                + (known.schemaName
+                    ? `\nOutput schema:   ${chalk.dim(`haystack schema ${known.schemaName}`)}`
+                    : '')
+                + `\n\nThe command validates its input strictly and reports every violation with a `
+                + `field path, so authoring against the contract and rerunning is the intended loop.`);
+            process.exit(2);
+        }
         console.error(chalk.red(`Unknown schema: "${name}".`) +
             `\n\nAvailable: ${VALID.join(', ')}`);
         process.exit(2);

package/dist/commands/skills.d.ts

@@ -1,6 +1,6 @@
 /**
- * Skills command - Copies Haystack skill files into the project
- * for AI agent discovery (Claude Code, Codex CLI, Cursor)
+ * Skills command - installs Haystack-owned skill files while preserving any
+ * customer-owned skills that share the discovery directories.
  */
 export declare function installSkills(options: {
     cli?: string;

package/dist/commands/skills.js

@@ -1,79 +1,447 @@
 /**
- * Skills command - Copies Haystack skill files into the project
- * for AI agent discovery (Claude Code, Codex CLI, Cursor)
+ * Skills command - installs Haystack-owned skill files while preserving any
+ * customer-owned skills that share the discovery directories.
  */
+import { createHash, randomUUID } from 'node:crypto';
+import { chmodSync, copyFileSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, posix, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { findGitRoot } from '../utils/hooks.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
-/** Directory containing bundled skill files */
+const MANIFEST_NAME = '.haystack-managed.json';
+const MANIFEST_SCHEMA_VERSION = 1;
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/;
+/** Directory containing bundled skill files. */
 function getSkillsSourceDir() {
-    // In dist/commands/skills.js → assets are at dist/assets/skills/
+    // In dist/commands/skills.js, assets are at dist/assets/skills/.
     return join(__dirname, '..', 'assets', 'skills');
 }
 const SKILL_FILES = [
-    'setup-haystack.md',
     'submit.md',
     'map-your-system.md',
 ];
-function installSkillFiles(targetDir) {
-    const sourceDir = getSkillsSourceDir();
-    if (!existsSync(sourceDir)) {
-        console.error(chalk.red(`Skills source directory not found: ${sourceDir}`));
+const SKILL_DIRECTORIES = [
+    'map-cloud-verifier-universe',
+];
+// The manifest-free installer predates every managed directory payload. Only
+// these fixed files can be classified as legacy Haystack content without an
+// ownership receipt; all other existing payload paths are user-owned.
+const LEGACY_MANAGED_FILE_PATHS = new Set([
+    'setup-haystack.md',
+    'submit.md',
+    'map-your-system.md',
+]);
+// Keep historical roots here after removing a bundled asset. They are the
+// only namespaces an earlier valid manifest may authorize us to clean up.
+const MANAGED_FILE_ROOTS = new Set(['setup-haystack.md', ...SKILL_FILES]);
+const MANAGED_DIRECTORY_ROOTS = new Set(SKILL_DIRECTORIES);
+const CLAUDE_MANAGED_FILE_ROOTS = new Set([
+    'setup-haystack.md',
+    'map-your-system.md',
+    'map-cloud-verifier-universe.md',
+]);
+const CLAUDE_COMMANDS = new Map([
+    [
+        'map-your-system.md',
+        '# Map Your System for Haystack QA\n\nFollow .agents/skills/map-your-system.md to create .haystack/system.yml — verified facts about how this system builds, boots, seeds data, and logs in, so Haystack QA can run it.\n',
+    ],
+    [
+        'map-cloud-verifier-universe.md',
+        '# Map a Cloud Verifier Universe\n\nFollow .agents/skills/map-cloud-verifier-universe/SKILL.md to map this application into a production-derived hermetic universe for on-demand Cloud Verifier.\n',
+    ],
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function entryExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function hasExactKeys(record, expected) {
+    const actual = Object.keys(record).sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function sha256(contents) {
+    return `sha256:${createHash('sha256').update(contents).digest('hex')}`;
+}
+function manifestDigest(files) {
+    return sha256(JSON.stringify(files.map(({ path, sha256: digest }) => ({ path, sha256: digest }))));
+}
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
+}
+function validateManagedPath(path) {
+    if (typeof path !== 'string' || path.length === 0 || path.includes('\\') || path.includes('\0')) {
+        return false;
+    }
+    if (isAbsolute(path) || posix.normalize(path) !== path)
         return false;
+    const components = path.split('/');
+    if (components.some((component) => component === '' || component === '.' || component === '..')) {
+        return false;
+    }
+    const [root] = components;
+    return ((components.length === 1 && MANAGED_FILE_ROOTS.has(root)) ||
+        (components.length > 1 && MANAGED_DIRECTORY_ROOTS.has(root)));
+}
+function destinationPath(targetDir, managedPath) {
+    return join(targetDir, ...managedPath.split('/'));
+}
+function assertExistingDirectoryInside(root, path) {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`Refusing skills install: destination ancestor is not a real directory: ${path}`);
+    }
+    const real = realpathSync(path);
+    if (!inside(root, real)) {
+        throw new Error(`Refusing skills install: destination escapes the repository: ${path}`);
     }
-    // Ensure target directory exists
-    if (!existsSync(targetDir)) {
-        mkdirSync(targetDir, { recursive: true });
+}
+/** Check every existing destination component without changing the repository. */
+function preflightDestination(root, relativeTarget) {
+    let current = root;
+    for (const component of relativeTarget) {
+        current = join(current, component);
+        if (!entryExists(current))
+            return;
+        assertExistingDirectoryInside(root, current);
+    }
+}
+/** Create one destination component at a time, rechecking each one for symlinks. */
+function ensureSafeDirectory(root, relativeTarget) {
+    let current = root;
+    for (const component of relativeTarget) {
+        current = join(current, component);
+        if (!entryExists(current))
+            mkdirSync(current, { mode: 0o755 });
+        assertExistingDirectoryInside(root, current);
+    }
+    return current;
+}
+function assertManagedLeafSafe(root, targetDir, managedPath) {
+    let current = targetDir;
+    const components = managedPath.split('/');
+    components.forEach((component, index) => {
+        current = join(current, component);
+        if (!entryExists(current))
+            return;
+        const stat = lstatSync(current);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Refusing skills install: managed path contains a symlink: ${managedPath}`);
+        }
+        if (index < components.length - 1 && !stat.isDirectory()) {
+            throw new Error(`Refusing skills install: managed path ancestor is not a directory: ${managedPath}`);
+        }
+        if (index === components.length - 1 && !stat.isFile()) {
+            throw new Error(`Refusing skills install: managed file path is not a regular file: ${managedPath}`);
+        }
+        const real = realpathSync(current);
+        if (!inside(root, real)) {
+            throw new Error(`Refusing skills install: managed path escapes the repository: ${managedPath}`);
+        }
+    });
+}
+function collectSourceDirectory(sourceDir, relativePrefix, payload) {
+    const sourceStat = lstatSync(sourceDir);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isDirectory()) {
+        throw new Error(`Bundled skill directory is not a real directory: ${sourceDir}`);
+    }
+    for (const entry of readdirSync(sourceDir, { withFileTypes: true }).sort((a, b) => compareText(a.name, b.name))) {
+        const source = join(sourceDir, entry.name);
+        const managedPath = posix.join(relativePrefix, entry.name);
+        const stat = lstatSync(source);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Bundled skills may not contain symlinks: ${source}`);
+        }
+        if (stat.isDirectory()) {
+            collectSourceDirectory(source, managedPath, payload);
+        }
+        else if (stat.isFile()) {
+            const contents = readFileSync(source);
+            payload.set(managedPath, {
+                path: managedPath,
+                sha256: sha256(contents),
+                contents,
+                mode: stat.mode & 0o777,
+            });
+        }
+        else {
+            throw new Error(`Bundled skills may contain only regular files and directories: ${source}`);
+        }
+    }
+}
+function bundledSkillsPayload() {
+    const sourceDir = getSkillsSourceDir();
+    if (!entryExists(sourceDir)) {
+        throw new Error(`Skills source directory not found: ${sourceDir}`);
     }
-    let copied = 0;
+    const payload = new Map();
     for (const file of SKILL_FILES) {
-        const src = join(sourceDir, file);
-        if (existsSync(src)) {
-            const dest = join(targetDir, file);
-            writeFileSync(dest, readFileSync(src, 'utf-8'));
-            copied++;
+        const source = join(sourceDir, file);
+        if (!entryExists(source))
+            continue;
+        const stat = lstatSync(source);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new Error(`Bundled skill file is not a regular file: ${source}`);
         }
+        const contents = readFileSync(source);
+        payload.set(file, {
+            path: file,
+            sha256: sha256(contents),
+            contents,
+            mode: stat.mode & 0o777,
+        });
+    }
+    for (const directory of SKILL_DIRECTORIES) {
+        const source = join(sourceDir, directory);
+        if (!entryExists(source))
+            continue;
+        collectSourceDirectory(source, directory, payload);
+    }
+    if (payload.size === 0)
+        throw new Error(`No bundled skills found in ${sourceDir}`);
+    return payload;
+}
+function textPayload(files) {
+    return new Map([...files.entries()].map(([path, text]) => {
+        const contents = Buffer.from(text, 'utf8');
+        return [path, { path, sha256: sha256(contents), contents, mode: 0o644 }];
+    }));
+}
+function parseManifest(targetDir, allowedPath) {
+    const path = join(targetDir, MANIFEST_NAME);
+    if (!entryExists(path))
+        return null;
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024 * 1024) {
+        throw new Error(`Refusing skills install: managed manifest is not a trusted regular file: ${path}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`Refusing skills install: managed manifest is malformed: ${path}`);
+    }
+    if (!isRecord(parsed) ||
+        !hasExactKeys(parsed, ['bundle_digest', 'files', 'schema_version']) ||
+        parsed.schema_version !== MANIFEST_SCHEMA_VERSION ||
+        typeof parsed.bundle_digest !== 'string' ||
+        !SHA256_PATTERN.test(parsed.bundle_digest) ||
+        !Array.isArray(parsed.files)) {
+        throw new Error(`Refusing skills install: managed manifest has an unsupported schema: ${path}`);
+    }
+    const files = [];
+    for (const value of parsed.files) {
+        if (!isRecord(value) ||
+            !hasExactKeys(value, ['path', 'sha256']) ||
+            !allowedPath(value.path) ||
+            typeof value.sha256 !== 'string' ||
+            !SHA256_PATTERN.test(value.sha256)) {
+            throw new Error(`Refusing skills install: managed manifest contains an unsafe entry: ${path}`);
+        }
+        files.push({ path: value.path, sha256: value.sha256 });
+    }
+    const sorted = [...files].sort((a, b) => compareText(a.path, b.path));
+    if (files.some((file, index) => file.path !== sorted[index]?.path) ||
+        files.some((file, index) => index > 0 && file.path === files[index - 1]?.path) ||
+        manifestDigest(files) !== parsed.bundle_digest) {
+        throw new Error(`Refusing skills install: managed manifest is inconsistent: ${path}`);
+    }
+    return {
+        schema_version: MANIFEST_SCHEMA_VERSION,
+        bundle_digest: parsed.bundle_digest,
+        files,
+    };
+}
+function copyTreeWithoutFollowingSymlinks(sourceDir, destinationDir) {
+    for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+        const source = join(sourceDir, entry.name);
+        const destination = join(destinationDir, entry.name);
+        const stat = lstatSync(source);
+        if (stat.isSymbolicLink()) {
+            symlinkSync(readlinkSync(source), destination);
+        }
+        else if (stat.isDirectory()) {
+            mkdirSync(destination, { mode: stat.mode & 0o777 });
+            copyTreeWithoutFollowingSymlinks(source, destination);
+        }
+        else if (stat.isFile()) {
+            copyFileSync(source, destination);
+            chmodSync(destination, stat.mode & 0o777);
+        }
+        else {
+            throw new Error(`Refusing skills install: destination contains an unsupported file type: ${source}`);
+        }
+    }
+}
+function writePayloadToStage(stageDir, payload, previouslyManaged, manifest) {
+    for (const managedPath of previouslyManaged) {
+        const stagedPath = destinationPath(stageDir, managedPath);
+        if (entryExists(stagedPath))
+            rmSync(stagedPath, { force: true });
+    }
+    for (const file of payload.values()) {
+        const destination = destinationPath(stageDir, file.path);
+        const parent = dirname(destination);
+        if (!entryExists(parent))
+            mkdirSync(parent, { recursive: true, mode: 0o755 });
+        if (entryExists(destination)) {
+            throw new Error(`Refusing skills install: new managed file collides with a user file: ${file.path}`);
+        }
+        writeFileSync(destination, file.contents, { mode: file.mode });
+    }
+    writeFileSync(join(stageDir, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}\n`, {
+        mode: 0o644,
+    });
+}
+function replaceDirectoryFromStage(targetDir, stageDir) {
+    const parent = dirname(targetDir);
+    const backupDir = join(parent, `.haystack-${posix.basename(targetDir)}-backup-${randomUUID()}`);
+    const targetExisted = entryExists(targetDir);
+    let oldMoved = false;
+    let newMoved = false;
+    try {
+        if (targetExisted) {
+            renameSync(targetDir, backupDir);
+            oldMoved = true;
+        }
+        renameSync(stageDir, targetDir);
+        newMoved = true;
+        if (oldMoved)
+            rmSync(backupDir, { recursive: true });
+    }
+    catch (error) {
+        try {
+            if (newMoved && entryExists(targetDir))
+                renameSync(targetDir, stageDir);
+            if (oldMoved && entryExists(backupDir) && !entryExists(targetDir)) {
+                renameSync(backupDir, targetDir);
+            }
+        }
+        finally {
+            if (entryExists(stageDir))
+                rmSync(stageDir, { recursive: true, force: true });
+        }
+        throw error;
     }
-    return copied > 0;
+}
+function installManagedPayload(root, relativeTarget, payload, allowedPath) {
+    const parent = ensureSafeDirectory(root, relativeTarget.slice(0, -1));
+    const targetDir = join(parent, relativeTarget[relativeTarget.length - 1]);
+    if (entryExists(targetDir))
+        assertExistingDirectoryInside(root, targetDir);
+    const previous = entryExists(targetDir) ? parseManifest(targetDir, allowedPath) : null;
+    const previouslyManaged = new Set(previous?.files.map((file) => file.path) ?? []);
+    if (previous) {
+        for (const file of previous.files) {
+            assertManagedLeafSafe(root, targetDir, file.path);
+            const existing = destinationPath(targetDir, file.path);
+            if (entryExists(existing) && sha256(readFileSync(existing)) !== file.sha256) {
+                throw new Error(`Refusing skills install: managed file was modified after installation: ${file.path}`);
+            }
+        }
+    }
+    for (const file of payload.values()) {
+        assertManagedLeafSafe(root, targetDir, file.path);
+        const existing = destinationPath(targetDir, file.path);
+        if (!entryExists(existing))
+            continue;
+        if ((previous && !previouslyManaged.has(file.path)) ||
+            (!previous && !LEGACY_MANAGED_FILE_PATHS.has(file.path))) {
+            throw new Error(`Refusing skills install: new managed file collides with a user file: ${file.path}`);
+        }
+        // One-time migration from the legacy installer: only its three historical
+        // fixed files may be adopted when no ownership manifest was written.
+        previouslyManaged.add(file.path);
+    }
+    const files = [...payload.values()]
+        .map(({ path, sha256: digest }) => ({ path, sha256: digest }))
+        .sort((a, b) => compareText(a.path, b.path));
+    const nextManifest = {
+        schema_version: MANIFEST_SCHEMA_VERSION,
+        bundle_digest: manifestDigest(files),
+        files,
+    };
+    const targetMode = entryExists(targetDir) ? lstatSync(targetDir).mode & 0o777 : 0o755;
+    const stageDir = mkdtempSync(join(parent, `.haystack-${relativeTarget.at(-1)}-stage-`));
+    try {
+        if (entryExists(targetDir))
+            copyTreeWithoutFollowingSymlinks(targetDir, stageDir);
+        writePayloadToStage(stageDir, payload, previouslyManaged, nextManifest);
+        chmodSync(stageDir, targetMode);
+        replaceDirectoryFromStage(targetDir, stageDir);
+    }
+    catch (error) {
+        if (entryExists(stageDir))
+            rmSync(stageDir, { recursive: true, force: true });
+        throw error;
+    }
+    return nextManifest;
+}
+function parseCli(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'claude' || value === 'codex' || value === 'cursor' || value === 'manual') {
+        return value;
+    }
+    throw new Error(`Unsupported coding CLI "${value}". Use claude, codex, cursor, or manual.`);
+}
+function claudeManagedPath(path) {
+    return typeof path === 'string' && CLAUDE_MANAGED_FILE_ROOTS.has(path);
 }
 export async function installSkills(options) {
     console.log(chalk.cyan('\n📦 Installing Haystack skills...\n'));
-    const projectRoot = process.cwd();
-    // Install to .agents/skills/ for generic agent discovery
+    const cli = parseCli(options.cli);
+    const gitRoot = findGitRoot();
+    if (!gitRoot) {
+        throw new Error('Skills must be installed from inside a Git repository.');
+    }
+    const projectRoot = realpathSync(gitRoot);
+    // Preflight all selected destinations before writing either one.
+    preflightDestination(projectRoot, ['.agents', 'skills']);
+    if (cli === 'claude')
+        preflightDestination(projectRoot, ['.claude', 'commands']);
     const agentsSkillsDir = join(projectRoot, '.agents', 'skills');
-    console.log(chalk.gray(`Copying skills to ${agentsSkillsDir}\n`));
-    const success = installSkillFiles(agentsSkillsDir);
-    if (!success) {
-        console.error(chalk.red('Failed to install skill files.'));
-        process.exit(1);
-    }
-    // Also create .claude/commands/ entry for Claude Code slash commands
-    const claudeCommandsDir = join(projectRoot, '.claude', 'commands');
-    if (!existsSync(claudeCommandsDir)) {
-        mkdirSync(claudeCommandsDir, { recursive: true });
-    }
-    const claudeCommandPath = join(claudeCommandsDir, 'setup-haystack.md');
-    writeFileSync(claudeCommandPath, '# Set Up Haystack\n\nFollow .agents/skills/setup-haystack.md to set up Haystack for this repo.\n');
-    writeFileSync(join(claudeCommandsDir, 'map-your-system.md'), '# Map Your System for Haystack QA\n\nFollow .agents/skills/map-your-system.md to create .haystack/system.yml — verified facts about how this system builds, boots, seeds data, and logs in, so Haystack QA can run it.\n');
-    showSuccessMessage();
-}
-function showSuccessMessage() {
+    console.log(chalk.gray(`Copying portable skills to ${agentsSkillsDir}\n`));
+    const skillsManifest = installManagedPayload(projectRoot, ['.agents', 'skills'], bundledSkillsPayload(), validateManagedPath);
+    if (cli === 'claude') {
+        installManagedPayload(projectRoot, ['.claude', 'commands'], textPayload(CLAUDE_COMMANDS), claudeManagedPath);
+    }
+    showSuccessMessage(cli, projectRoot, skillsManifest.bundle_digest);
+}
+function showSuccessMessage(cli, projectRoot, digest) {
     console.log(chalk.green('\n✅ Haystack skills installed!\n'));
-    console.log(chalk.white('Available skills:'));
-    console.log(chalk.cyan('  /setup-haystack         ') + chalk.gray('- Create .haystack.json with AI assistance'));
+    console.log(chalk.gray(`Repository: ${projectRoot}`));
+    console.log(chalk.gray(`Bundle: ${digest}`));
+    console.log(chalk.white('\nAvailable skills:'));
     console.log(chalk.cyan('  /submit                 ') + chalk.gray('- Submit a PR via Haystack'));
     console.log(chalk.cyan('  /map-your-system        ') + chalk.gray('- Write .haystack/system.yml so Haystack QA can run this system'));
-    console.log();
-    console.log(chalk.white('Run in your coding CLI:'));
-    console.log(chalk.cyan('  /setup-haystack'));
+    console.log(chalk.cyan('  /map-cloud-verifier-universe') + chalk.gray(' - Map a production-derived hermetic Cloud Verifier universe'));
+    if (cli === 'claude') {
+        console.log(chalk.gray('\nClaude Code command shims were installed in .claude/commands.'));
+    }
+    else if (cli === 'manual') {
+        console.log(chalk.gray('\nPoint your coding agent at .agents/skills for portable skill discovery.'));
+    }
     console.log();
 }
 export async function listSkills() {
     console.log(chalk.white('\nAvailable Haystack skills:\n'));
-    console.log(chalk.cyan('  /setup-haystack         ') + chalk.gray('- Master setup - creates .haystack.json'));
     console.log(chalk.cyan('  /submit                 ') + chalk.gray('- Submit a PR via Haystack'));
     console.log(chalk.cyan('  /map-your-system        ') + chalk.gray('- Write .haystack/system.yml so Haystack QA can run this system'));
+    console.log(chalk.cyan('  /map-cloud-verifier-universe') + chalk.gray(' - Map a production-derived hermetic Cloud Verifier universe'));
     console.log();
 }

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,53 @@
+declare const MANIFEST_SCHEMA_VERSION = "haystack-node-telemetry-instrumentation-v3";
+export interface TelemetryInstrumentOptions {
+    entry: string;
+    sourceRoot?: string;
+    json?: boolean;
+    /**
+     * Experimental exact symbol allow-list. Entries use the same structured
+     * sourcePath#qualifiedName coordinates emitted in the instrumentation
+     * manifest. No fuzzy name matching is performed.
+     */
+    includeSymbols?: Array<{
+        sourcePath: string;
+        qualifiedName: string;
+    }>;
+}
+export interface InstrumentedFileSummary {
+    output_path: string;
+    source_path: string;
+    probes: {
+        branches: number;
+        parameters: number;
+        bindings: number;
+        returns: number;
+        throws: number;
+    };
+}
+export interface TelemetryInstrumentationResult {
+    schema_version: typeof MANIFEST_SCHEMA_VERSION;
+    build_id: string;
+    dist_directory: string;
+    entry: string;
+    runtime: string;
+    instrumented_files: InstrumentedFileSummary[];
+    sites: InstrumentedSite[];
+    skipped_unmapped_files: string[];
+    already_instrumented: boolean;
+}
+export interface InstrumentedSite {
+    probe_key: string;
+    site_id: string;
+    source_path: string;
+    qualified_name: string;
+    probe_kind: 'condition' | 'parameter' | 'binding' | 'return' | 'throw';
+    owner_key: string;
+    structural_key: string;
+    label?: string;
+    allowed_fields: string[];
+}
+export declare function instrumentNodeTelemetryBuild(distDirectory: string, options: TelemetryInstrumentOptions): TelemetryInstrumentationResult;
+export declare function telemetryInstrumentCommand(distDirectory: string, options: TelemetryInstrumentOptions & {
+    includeSymbolsFile?: string;
+}): Promise<void>;
+export {};