@codeledger/instrument 0.1.1

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025 Intelligent Context AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: This license applies to the CLI wrapper, types, repository scanning,
+instrumentation, harness, and report packages (the "Plugin"). The scoring
+engine (packages/core-engine/bin/) is licensed separately under LICENSE-CORE.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { runPreflight, validatePreflight } from './preflight.js';
+export { validateGitRef, ensureCleanOrFail, resolveRef, getHeadCommit, getShortRef, isRepoDirty, } from './snapshotter.js';
+export { execCommand, execCommandAsync } from './process-probe.js';
+export { RunRecorder } from './recorder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { runPreflight, validatePreflight } from './preflight.js';
+export { validateGitRef, ensureCleanOrFail, resolveRef, getHeadCommit, getShortRef, isRepoDirty, } from './snapshotter.js';
+export { execCommand, execCommandAsync } from './process-probe.js';
+export { RunRecorder } from './recorder.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/preflight.d.ts

@@ -0,0 +1,8 @@
+import type { PreflightResult } from '@codeledger/types';
+export declare function runPreflight(cwd: string, configPath?: string, indexPath?: string): PreflightResult;
+export declare function validatePreflight(result: PreflightResult, level: 'init' | 'scan' | 'bundle' | 'run', force?: boolean): {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+};
+//# sourceMappingURL=preflight.d.ts.map

package/dist/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,eAAe,CAsFjB;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,EACzC,KAAK,GAAE,OAAe,GACrB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA8CvD"}

package/dist/preflight.js

@@ -0,0 +1,126 @@
+import { execSync } from 'node:child_process';
+import { existsSync, accessSync, constants } from 'node:fs';
+import { join } from 'node:path';
+export function runPreflight(cwd, configPath, indexPath) {
+    const result = {
+        git_installed: false,
+        inside_git_repo: false,
+        repo_clean: false,
+        worktree_supported: false,
+        worktree_root_writable: false,
+        node_version: process.version,
+        config_exists: false,
+        repo_index_exists: false,
+    };
+    // Check git installed
+    try {
+        execSync('git --version', { cwd, encoding: 'utf-8', stdio: 'pipe' });
+        result.git_installed = true;
+    }
+    catch {
+        return result;
+    }
+    // Check inside git repo
+    try {
+        execSync('git rev-parse --git-dir', { cwd, encoding: 'utf-8', stdio: 'pipe' });
+        result.inside_git_repo = true;
+    }
+    catch {
+        return result;
+    }
+    // Check repo clean
+    try {
+        const status = execSync('git status --porcelain', {
+            cwd,
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        });
+        result.repo_clean = status.trim().length === 0;
+    }
+    catch {
+        // Treat error as dirty
+    }
+    // Check worktree support (git >= 2.15)
+    try {
+        const versionStr = execSync('git --version', {
+            cwd,
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        });
+        const match = versionStr.match(/(\d+)\.(\d+)/);
+        if (match) {
+            const major = parseInt(match[1], 10);
+            const minor = parseInt(match[2], 10);
+            result.worktree_supported = major > 2 || (major === 2 && minor >= 15);
+        }
+    }
+    catch {
+        // Assume not supported
+    }
+    // Check worktree root writable
+    const worktreeRoot = join(cwd, '.codeledger', 'worktrees');
+    try {
+        if (existsSync(worktreeRoot)) {
+            accessSync(worktreeRoot, constants.W_OK);
+            result.worktree_root_writable = true;
+        }
+        else {
+            // Check parent writable
+            const parent = join(cwd, '.codeledger');
+            if (existsSync(parent)) {
+                accessSync(parent, constants.W_OK);
+                result.worktree_root_writable = true;
+            }
+        }
+    }
+    catch {
+        // Not writable
+    }
+    // Check config exists
+    if (configPath) {
+        result.config_exists = existsSync(configPath);
+    }
+    // Check repo index exists
+    if (indexPath) {
+        result.repo_index_exists = existsSync(indexPath);
+    }
+    return result;
+}
+export function validatePreflight(result, level, force = false) {
+    const errors = [];
+    const warnings = [];
+    if (!result.git_installed) {
+        errors.push('Git is not installed. Install git and try again.');
+    }
+    if (!result.inside_git_repo) {
+        errors.push('Not inside a git repository. Run "git init" first.');
+    }
+    if (level === 'init') {
+        return { ok: errors.length === 0, errors, warnings };
+    }
+    if (!result.config_exists) {
+        errors.push('No .codeledger/config.json found. Run "codeledger init" first.');
+    }
+    if (level === 'scan') {
+        return { ok: errors.length === 0, errors, warnings };
+    }
+    if (!result.repo_index_exists && level !== 'bundle') {
+        errors.push('No repo index found. Run "codeledger scan" first.');
+    }
+    if (level === 'run') {
+        if (!result.repo_clean && !force) {
+            warnings.push('Working directory has uncommitted changes. Use --force to proceed or commit first.');
+        }
+        if (!result.worktree_supported) {
+            warnings.push('Git worktree not supported (requires git >= 2.15). Worktrees will be disabled.');
+        }
+    }
+    const hasBlockingWarnings = !force && warnings.length > 0 &&
+        warnings.some((w) => w.includes('uncommitted'));
+    return {
+        ok: errors.length === 0 && !hasBlockingWarnings,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"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"}

package/dist/process-probe.d.ts

@@ -0,0 +1,14 @@
+import type { ExecResult } from '@codeledger/types';
+export declare function execCommand(cmd: string, opts?: {
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+}): ExecResult;
+export declare function execCommandAsync(cmd: string, opts?: {
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+    stdoutLog?: string;
+    stderrLog?: string;
+}): Promise<ExecResult>;
+//# sourceMappingURL=process-probe.d.ts.map

package/dist/process-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-probe.d.ts","sourceRoot":"","sources":["../src/process-probe.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB,GACL,UAAU,CA8BZ;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,UAAU,CAAC,CA4DrB"}

package/dist/process-probe.js

@@ -0,0 +1,87 @@
+import { execSync, spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+export function execCommand(cmd, opts = {}) {
+    const start = Date.now();
+    try {
+        const stdout = execSync(cmd, {
+            cwd: opts.cwd,
+            encoding: 'utf-8',
+            timeout: opts.timeout ?? 300_000,
+            env: { ...process.env, ...opts.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 50 * 1024 * 1024,
+        });
+        return {
+            exit_code: 0,
+            duration_ms: Date.now() - start,
+            stdout,
+            stderr: '',
+        };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            exit_code: e.status ?? 1,
+            duration_ms: Date.now() - start,
+            stdout: e.stdout ?? '',
+            stderr: e.stderr ?? '',
+        };
+    }
+}
+export async function execCommandAsync(cmd, opts = {}) {
+    return new Promise((resolve) => {
+        const start = Date.now();
+        const child = spawn('sh', ['-c', cmd], {
+            cwd: opts.cwd,
+            env: { ...process.env, ...opts.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        let timedOut = false;
+        const timer = opts.timeout
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, opts.timeout)
+            : null;
+        child.on('error', (err) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                exit_code: 1,
+                duration_ms: Date.now() - start,
+                stdout,
+                stderr: stderr || String(err),
+            });
+        });
+        child.on('close', (code) => {
+            if (timer)
+                clearTimeout(timer);
+            try {
+                if (opts.stdoutLog) {
+                    writeFileSync(opts.stdoutLog, stdout);
+                }
+                if (opts.stderrLog) {
+                    writeFileSync(opts.stderrLog, stderr);
+                }
+            }
+            catch {
+                // Non-fatal: log write failure should not prevent result delivery
+            }
+            resolve({
+                exit_code: timedOut ? 124 : (code ?? 1),
+                duration_ms: Date.now() - start,
+                stdout,
+                stderr,
+            });
+        });
+    });
+}
+//# sourceMappingURL=process-probe.js.map

package/dist/process-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-probe.js","sourceRoot":"","sources":["../src/process-probe.ts"],"names":[],"mappings":"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"}

package/dist/recorder.d.ts

@@ -0,0 +1,12 @@
+import { LedgerStore } from '@codeledger/core';
+import type { RunIdentity, RunStatus, EventType } from '@codeledger/types';
+export declare class RunRecorder {
+    private ledger;
+    private runId;
+    constructor(ledger: LedgerStore, runId?: string);
+    get id(): string;
+    startRun(identity: Omit<RunIdentity, 'run_id'>): void;
+    recordEvent(type: EventType, payload: unknown): void;
+    finishRun(status: RunStatus, summary?: unknown): void;
+}
+//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAEV,WAAW,EACX,SAAS,EACT,SAAS,EAEV,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,MAAM;IAK/C,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,GAAG,IAAI;IAOrD,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAWpD,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;CAGtD"}

package/dist/recorder.js

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+export class RunRecorder {
+    ledger;
+    runId;
+    constructor(ledger, runId) {
+        this.ledger = ledger;
+        this.runId = runId ?? `run_${randomUUID().slice(0, 12)}`;
+    }
+    get id() {
+        return this.runId;
+    }
+    startRun(identity) {
+        this.ledger.startRun({
+            ...identity,
+            run_id: this.runId,
+        });
+    }
+    recordEvent(type, payload) {
+        const event = {
+            event_id: `evt_${randomUUID().slice(0, 12)}`,
+            run_id: this.runId,
+            ts: new Date().toISOString(),
+            type,
+            payload,
+        };
+        this.ledger.append(event);
+    }
+    finishRun(status, summary) {
+        this.ledger.finishRun(this.runId, status, summary);
+    }
+}
+//# sourceMappingURL=recorder.js.map

package/dist/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAUzC,MAAM,OAAO,WAAW;IACd,MAAM,CAAc;IACpB,KAAK,CAAS;IAEtB,YAAY,MAAmB,EAAE,KAAc;QAC7C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,OAAO,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IAC3D,CAAC;IAED,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,QAAQ,CAAC,QAAqC;QAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;YACnB,GAAG,QAAQ;YACX,MAAM,EAAE,IAAI,CAAC,KAAK;SACnB,CAAC,CAAC;IACL,CAAC;IAED,WAAW,CAAC,IAAe,EAAE,OAAgB;QAC3C,MAAM,KAAK,GAAgB;YACzB,QAAQ,EAAE,OAAO,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;YAC5C,MAAM,EAAE,IAAI,CAAC,KAAK;YAClB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAiB;YAC3C,IAAI;YACJ,OAAO;SACR,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,SAAS,CAAC,MAAiB,EAAE,OAAiB;QAC5C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;CACF"}

package/dist/snapshotter.d.ts

@@ -0,0 +1,7 @@
+export declare function validateGitRef(ref: string): void;
+export declare function ensureCleanOrFail(root: string): void;
+export declare function resolveRef(root: string, ref: string): string;
+export declare function getHeadCommit(root: string): string;
+export declare function getShortRef(root: string): string;
+export declare function isRepoDirty(root: string): boolean;
+//# sourceMappingURL=snapshotter.d.ts.map

package/dist/snapshotter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotter.d.ts","sourceRoot":"","sources":["../src/snapshotter.ts"],"names":[],"mappings":"AAIA,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAIhD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAYpD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO5D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOjD"}

package/dist/snapshotter.js

@@ -0,0 +1,44 @@
+import { execFileSync } from 'node:child_process';
+const GIT_REF_PATTERN = /^[a-zA-Z0-9._\-/~^@{}]+$/;
+export function validateGitRef(ref) {
+    if (!GIT_REF_PATTERN.test(ref)) {
+        throw new Error(`Invalid git ref: "${ref}" contains disallowed characters`);
+    }
+}
+export function ensureCleanOrFail(root) {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+        cwd: root,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (status.length > 0) {
+        throw new Error('Working directory is not clean. Commit or stash changes before running.');
+    }
+}
+export function resolveRef(root, ref) {
+    validateGitRef(ref);
+    return execFileSync('git', ['rev-parse', '--verify', ref], {
+        cwd: root,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+export function getHeadCommit(root) {
+    return resolveRef(root, 'HEAD');
+}
+export function getShortRef(root) {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+        cwd: root,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+export function isRepoDirty(root) {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+        cwd: root,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return status.length > 0;
+}
+//# sourceMappingURL=snapshotter.js.map

package/dist/snapshotter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotter.js","sourceRoot":"","sources":["../src/snapshotter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAEnD,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,kCAAkC,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE;QAC5D,GAAG,EAAE,IAAI;QACT,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEV,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,yEAAyE,CAC1E,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,GAAW;IAClD,cAAc,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE;QACzD,GAAG,EAAE,IAAI;QACT,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE;QAC3D,GAAG,EAAE,IAAI;QACT,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE;QAC5D,GAAG,EAAE,IAAI;QACT,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC,IAAI,EAAE,CAAC;IACV,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@codeledger/instrument",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Runtime instrumentation and recording for CodeLedger",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codeledgerECF/codeledger-blackbox.git",
+    "directory": "packages/instrument"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@codeledger/types": "0.1.1",
+    "@codeledger/core": "0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}