tracegrove 0.0.0-stage → 0.3.0

package/dist/authoring/discover.d.ts

@@ -0,0 +1,43 @@
+export type Route = {
+    method: string;
+    path: string;
+    file: string;
+    line: number;
+    framework: 'fastapi' | 'django' | 'express';
+};
+export type FlowRef = {
+    caseId: string;
+    method: string;
+    path: string;
+};
+export type CoveredRoute = Route & {
+    coveredBy: string[];
+    changed: boolean;
+};
+export type GitInfo = {
+    isRepo: boolean;
+    current: string | null;
+    base: string | null;
+    branches: string[];
+};
+export type Discovery = {
+    source: string;
+    branch: string | null;
+    base: string | null;
+    files: number;
+    changedFiles: string[];
+    routes: CoveredRoute[];
+    uncovered: number;
+};
+export declare function gitInfo(dir: string): GitInfo;
+export declare function scanSource(file: string, text: string): Route[];
+export declare function discover(dir: string, flows: FlowRef[], branch: string | null): Discovery;
+/** A starting flow for one route; placeholders the author must fill are marked TODO. */
+export declare function draftFlow(route: {
+    method: string;
+    path: string;
+}): {
+    file: string;
+    yaml: string;
+};
+export declare function hasConfig(dir: string): boolean;

package/dist/authoring/discover.js

@@ -0,0 +1,149 @@
+/**
+ * Discovery: find HTTP routes in a folder (or at a git branch) and match them against flows.
+ * Heuristic static scan for FastAPI, Django and Express-style routers; it proposes what to test
+ * and drafts flow skeletons. It is not evidence and never runs the app.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { Blocked } from "../core/errors.js";
+const SKIP = new Set(['node_modules', '.git', '.venv', 'venv', '__pycache__', '.tracegrove', 'dist', 'build', '.next', 'coverage', 'migrations']);
+const EXT = /\.(py|js|mjs|cjs|ts|mts|jsx|tsx)$/;
+const MAX_FILES = 5000;
+const MAX_BYTES = 512 * 1024;
+function git(dir, args) {
+    return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+}
+function safeRef(name) {
+    if (!/^[A-Za-z0-9._\/-]+$/.test(name) || name.startsWith('-') || name.includes('..'))
+        throw new Blocked([{ code: 'invalid_branch', detail: name, owner: 'operator', action: 'pick a branch from the list' }]);
+    return name;
+}
+export function gitInfo(dir) {
+    try {
+        if (git(dir, ['rev-parse', '--is-inside-work-tree']).trim() !== 'true')
+            throw new Error('not a repo');
+    }
+    catch {
+        return { isRepo: false, current: null, base: null, branches: [] };
+    }
+    const branches = git(dir, ['for-each-ref', '--format=%(refname:short)', 'refs/heads', 'refs/remotes']).split('\n').map((b) => b.trim()).filter((b) => b && !b.endsWith('/HEAD'));
+    let current = null;
+    try {
+        current = git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']).trim();
+    }
+    catch { /* unborn */ }
+    let base = null;
+    try {
+        base = git(dir, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']).trim();
+    }
+    catch { /* no remote head */ }
+    base ??= ['main', 'master', 'origin/main', 'origin/master'].find((b) => branches.includes(b)) ?? null;
+    return { isRepo: true, current, base, branches };
+}
+function workingTree(dir) {
+    const files = [];
+    const walk = (rel) => {
+        for (const entry of readdirSync(join(dir, rel), { withFileTypes: true })) {
+            if (files.length >= MAX_FILES)
+                return;
+            const path = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!SKIP.has(entry.name))
+                    walk(path);
+            }
+            else if (entry.isFile() && EXT.test(entry.name) && statSync(join(dir, path)).size <= MAX_BYTES)
+                files.push(path);
+        }
+    };
+    walk('');
+    return { files, read: (file) => readFileSync(join(dir, file), 'utf8') };
+}
+function atBranch(dir, branch) {
+    const files = git(dir, ['ls-tree', '-r', '--name-only', branch]).split('\n')
+        .filter((f) => f && EXT.test(f) && !f.split('/').some((part) => SKIP.has(part))).slice(0, MAX_FILES);
+    return { files, read: (file) => git(dir, ['show', `${branch}:${file}`]) };
+}
+function normalizePath(path) {
+    const withSlash = path.startsWith('/') ? path : `/${path}`;
+    return withSlash.replace(/<(?:\w+:)?(\w+)>/g, '{$1}').replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, '{$1}').replace(/\/+$/, '') || '/';
+}
+export function scanSource(file, text) {
+    const routes = [];
+    const lineOf = (index) => text.slice(0, index).split('\n').length;
+    if (file.endsWith('.py')) {
+        for (const m of text.matchAll(/@\w+\.(get|post|put|patch|delete|head)\(\s*[rf]?["']([^"']*)["']/g))
+            routes.push({ method: m[1].toUpperCase(), path: normalizePath(m[2]), file, line: lineOf(m.index), framework: 'fastapi' });
+        for (const m of text.matchAll(/\bpath\(\s*["']([^"']*)["']/g))
+            routes.push({ method: 'ANY', path: normalizePath(m[1]), file, line: lineOf(m.index), framework: 'django' });
+    }
+    else {
+        for (const m of text.matchAll(/\b(?:app|router|server|fastify|api|routes)\.(get|post|put|patch|delete|head)\(\s*["'`]([^"'`]+)["'`]/g))
+            routes.push({ method: m[1].toUpperCase(), path: normalizePath(m[2]), file, line: lineOf(m.index), framework: 'express' });
+    }
+    return routes.filter((r) => !r.path.includes('${'));
+}
+const shape = (path) => normalizePath(path).replace(/\{[^}]*\}/g, '{}');
+export function discover(dir, flows, branch) {
+    const info = gitInfo(dir);
+    const ref = branch ? safeRef(branch) : null;
+    if (ref && !info.isRepo)
+        throw new Blocked([{ code: 'not_a_git_repo', detail: dir, owner: 'operator', action: 'drop --branch, or point at a git checkout' }]);
+    const source = ref ? atBranch(dir, ref) : workingTree(dir);
+    let changedFiles = [];
+    if (ref && info.base && info.base !== ref) {
+        try {
+            changedFiles = git(dir, ['diff', '--name-only', `${safeRef(info.base)}...${ref}`]).split('\n').filter(Boolean);
+        }
+        catch {
+            changedFiles = [];
+        }
+    }
+    const changed = new Set(changedFiles);
+    const routes = [];
+    const seen = new Set();
+    for (const file of source.files) {
+        let text;
+        try {
+            text = source.read(file);
+        }
+        catch {
+            continue;
+        }
+        if (!/(get|post|put|patch|delete|path)\(/.test(text))
+            continue;
+        for (const route of scanSource(file, text)) {
+            const key = `${route.method} ${route.path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const coveredBy = [...new Set(flows.filter((f) => shape(f.path) === shape(route.path) && (route.method === 'ANY' || f.method === route.method)).map((f) => f.caseId))];
+            routes.push({ ...route, coveredBy, changed: changed.has(route.file) });
+        }
+    }
+    routes.sort((a, b) => Number(b.changed) - Number(a.changed) || a.coveredBy.length - b.coveredBy.length || a.path.localeCompare(b.path));
+    return { source: ref ? `branch ${ref}` : 'working tree', branch: ref, base: info.base, files: source.files.length, changedFiles, routes, uncovered: routes.filter((r) => r.coveredBy.length === 0).length };
+}
+/** A starting flow for one route; placeholders the author must fill are marked TODO. */
+export function draftFlow(route) {
+    const method = route.method === 'ANY' ? 'GET' : route.method;
+    const params = [...route.path.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]);
+    const segments = route.path.split('/').filter((s) => s && !s.startsWith('{'));
+    const area = (segments[0] ?? 'root').replace(/[^A-Za-z0-9-]/g, '-').toLowerCase();
+    const behavior = `${method.toLowerCase()}-${segments.slice(1).join('-') || (params.length ? 'by-id' : 'collection')}`.replace(/[^A-Za-z0-9-]/g, '-').toLowerCase();
+    const lines = [`title: ${method} ${route.path} behaves as intended  # TODO: say what should be true`, 'tags: [discovered]', 'steps:'];
+    if (params.length) {
+        lines.push('  # TODO: create the resource first and save its id, e.g.', `  # - name: create`, `  #   POST: /${segments[0] ?? ''}`, '  #   json: { }', '  #   expect: 201', `  #   save: { ${params[0]}: id }`);
+    }
+    lines.push(`  - name: ${method.toLowerCase()} ${route.path}`, `    ${method}: ${route.path}`);
+    if (['POST', 'PUT', 'PATCH'].includes(method))
+        lines.push('    json: { }  # TODO: request body');
+    lines.push(`    expect: ${method === 'POST' ? 201 : method === 'DELETE' ? 204 : 200}`);
+    if (method !== 'DELETE')
+        lines.push('  - name: stranger is denied  # TODO: keep if the route is per-user', `    ${method === 'POST' ? 'GET' : method}: ${route.path}`, '    as: none', '    expect: 401');
+    return { file: `${area}/${behavior}.flow.yaml`, yaml: `${lines.join('\n')}\n` };
+}
+export function hasConfig(dir) {
+    return existsSync(join(dir, 'tracegrove.config.yaml'));
+}
+//# sourceMappingURL=discover.js.map

package/dist/authoring/discover.js.map

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

package/dist/authoring/environmentTemplates.d.ts

@@ -0,0 +1,3 @@
+/** Safe reference-only SDK examples, not registered hosts or executable CLI configurations. */
+import { PortableEnvironmentProfile } from '../protocol/index.ts';
+export declare function portableEnvironmentTemplate(mode: 'alongside_runner' | 'external_staging'): PortableEnvironmentProfile;

package/dist/authoring/environmentTemplates.js

@@ -0,0 +1,24 @@
+/** Safe reference-only SDK examples, not registered hosts or executable CLI configurations. */
+import { PortableEnvironmentProfile, freeze, digestOfBytes } from "../protocol/index.js";
+const placeholder = (id) => ({ id: `example.${id}`, revision: '1', digest: digestOfBytes(`unresolved example reference: ${id}`) });
+export function portableEnvironmentTemplate(mode) {
+    return PortableEnvironmentProfile.parse(freeze({ schemaVersion: 'workflow.portable-environment-profile/v1',
+        ref: { id: `example.profile.${mode}`, revision: '1' }, scope: { ownerId: 'example.owner', tenantId: null, visibility: 'owner_private' },
+        sourceSelectionRef: placeholder('source-selection'), buildRef: placeholder('build'), configurationRef: placeholder('non-secret-config'),
+        target: mode === 'alongside_runner'
+            ? { mode, workspaceRef: placeholder('workspace'), hostPlanRef: placeholder('host-plan'), launchRecipeRef: placeholder('launch-recipe') }
+            : { mode, deploymentRef: placeholder('deployment') },
+        endpoints: [{ id: 'app', resolverRef: placeholder('app-endpoint'), source: mode === 'alongside_runner' ? 'launch_reported' : 'external_deployment' }],
+        readiness: { endpointId: 'app', path: '/health', method: 'GET', expectedStatus: 200, timeoutMs: 20_000 },
+        capabilities: [{ id: 'surface.http', version: 1, required: true }], dependencyPlanRefs: [],
+        personaCredentials: [{ personaRef: placeholder('persona.owner'), secretRef: placeholder('app-persona-credential') }],
+        executionPolicyRef: placeholder('execution-policy'), executionSecretRefs: [],
+        network: { policyRef: placeholder('network-policy'), enforcement: 'host', inbound: mode === 'alongside_runner' ? 'loopback_only' : 'none', egress: 'explicit_allowlist', allowedEndpointIds: ['app'] },
+        data: { mode: 'none' },
+        ownership: { leasePolicyRef: placeholder('lease-policy'), cleanupPlanRef: placeholder('cleanup-plan'), cleanupReserveMs: 10_000 },
+        artifacts: { destinationRef: placeholder('artifact-destination'), durability: 'export_required', redactionPolicyRef: placeholder('redaction-policy'), retentionMs: 86_400_000, maxBytes: 16_777_216 },
+        limits: { wallMs: 120_000, cpu: 1, memoryMb: 1024, diskMb: 256, maxRequests: 100, maxBrowserActions: 0,
+            maxProviderCalls: 0, maxAgentCalls: 0, maxSpendCents: 0 },
+        allowedReplayModes: ['fresh_execution', 'evidence_playback'], }));
+}
+//# sourceMappingURL=environmentTemplates.js.map

package/dist/authoring/environmentTemplates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environmentTemplates.js","sourceRoot":"","sources":["../../src/authoring/environmentTemplates.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,OAAO,EAAE,0BAA0B,EAAE,MAAM,EAAE,aAAa,EAAY,MAAM,sBAAsB,CAAC;AACnG,MAAM,WAAW,GAAG,CAAC,EAAU,EAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,iCAAiC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;AAChJ,MAAM,UAAU,2BAA2B,CAAC,IAA6C;IACvF,OAAO,0BAA0B,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,0CAAmD;QACjH,GAAG,EAAE,EAAE,EAAE,EAAE,mBAAmB,IAAI,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,eAAwB,EAAE;QAChJ,kBAAkB,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,gBAAgB,EAAE,WAAW,CAAC,mBAAmB,CAAC;QACvI,MAAM,EAAE,IAAI,KAAK,kBAAkB;YACjC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,EAAE,eAAe,EAAE,WAAW,CAAC,eAAe,CAAC,EAAE;YACxI,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,CAAC,YAAY,CAAC,EAAE;QACtD,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC;QACrJ,SAAS,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE;QACxG,YAAY,EAAE,CAAC,EAAE,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,kBAAkB,EAAE,EAAE;QAC1F,kBAAkB,EAAE,CAAC,EAAE,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,wBAAwB,CAAC,EAAE,CAAC;QACpH,kBAAkB,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAAE,mBAAmB,EAAE,EAAE;QAC5E,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC,KAAK,CAAC,EAAE;QACtM,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;QACtB,SAAS,EAAE,EAAE,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,EAAE,gBAAgB,EAAE,MAAM,EAAE;QACjI,SAAS,EAAE,EAAE,cAAc,EAAE,WAAW,CAAC,sBAAsB,CAAC,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE;QACrM,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,iBAAiB,EAAE,CAAC;YACpG,gBAAgB,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE;QAC3D,kBAAkB,EAAE,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,GAC7D,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/authoring/heal.d.ts

@@ -0,0 +1,108 @@
+import { type CaseReport, type TestRunReport } from './run.ts';
+import { type CheckIssue } from './workspace.ts';
+import { type AgentOverrides } from './agent.ts';
+import type { AuthoringConfig } from './schema.ts';
+export type FindingKind = 'setup' | 'authoring' | 'test_drift' | 'product_bug' | 'assertion' | 'evidence' | 'infrastructure';
+export type HealFinding = {
+    kind: FindingKind;
+    caseId: string | null;
+    file: string | null;
+    step: string | null;
+    detail: string;
+    fix: string;
+    status: 'fixed' | 'open' | 'reported';
+};
+export type HealChange = {
+    file: string;
+    reason: string;
+    diff: string;
+    status: 'kept' | 'reverted' | 'rejected';
+    by: 'tracegrove' | 'agent';
+    note: string | null;
+};
+export type HealVerdict = {
+    caseId: string;
+    verdict: 'test_drift' | 'product_bug' | 'unsure';
+    reason: string;
+};
+export type HealSnapshot = {
+    outcome: string;
+    exitCode: number;
+    runDir: string | null;
+    totals: TestRunReport['totals'] | null;
+    issues: number;
+};
+export type HealReport = {
+    schemaVersion: 'tracegrove.heal/v1';
+    id: string;
+    root: string;
+    startedAt: string;
+    finishedAt: string;
+    outcome: 'healthy' | 'healed' | 'partly_healed' | 'product_bugs' | 'needs_human' | 'cancelled';
+    exitCode: number;
+    before: HealSnapshot;
+    after: HealSnapshot;
+    findings: HealFinding[];
+    changes: HealChange[];
+    agent: {
+        provider: string;
+        model: string | null;
+        exitCode: number;
+        verdicts: HealVerdict[];
+        summary: string;
+    } | null;
+    next: Array<{
+        command: string;
+        why: string;
+    }>;
+    reportPath: string;
+    /** Complete retained file images; old reports without these cannot authorize automatic undo. */
+    fileBindings?: Array<{
+        file: string;
+        beforeSha256: string;
+        afterSha256: string;
+    }>;
+};
+export type HealOptions = {
+    dir: string;
+    /** Start from this run report instead of running the suite first (tracegrove test --heal). */
+    report?: TestRunReport | undefined;
+    agent?: boolean | undefined;
+    overrides?: AgentOverrides | undefined;
+    dryRun?: boolean | undefined;
+    onProgress?: ((phase: string, detail?: string) => void) | undefined;
+    onAgentOutput?: ((chunk: string) => void) | undefined;
+    /** Readable lines of what the agent is doing (reading, editing, saying). */
+    onAgentActivity?: ((line: string) => void) | undefined;
+    signal?: AbortSignal | undefined;
+};
+export declare const HEALS_DIR = "heals";
+/** A small line diff (LCS) good enough for config and flow files. */
+export declare function lineDiff(before: string, after: string, name: string): string;
+/** Turn a run report (and compile issues) into findings a person or agent can act on. */
+export declare function classify(report: TestRunReport | null, issues: CheckIssue[]): HealFinding[];
+/** Health paths the app plausibly serves: declared GET routes first, then string literals in its source. */
+export declare function healthCandidates(root: string, config: AuthoringConfig, current: string): string[];
+/** Interpreters worth trying for fastapi/django, in the order a developer would expect. */
+export declare function pythonCandidates(root: string, config: AuthoringConfig): string[];
+/** Why an agent's edit to a flow would weaken it, or null when it keeps the test's strength. */
+export declare function guardFlowEdit(before: string, after: string): string | null;
+export declare function parseVerdicts(output: string): HealVerdict[];
+export declare function buildHealPrompt(input: {
+    root: string;
+    failing: CaseReport[];
+    issues: CheckIssue[];
+    tracegrove?: string[];
+}): string;
+/** Diagnose, repair what is safe, verify, and write .tracegrove/heals/<id>/report.json. */
+export declare function heal(options: HealOptions): Promise<HealReport>;
+export declare function listHeals(root: string): HealReport[];
+/** Restore every file a heal kept a change to. Refuses when the file changed again since. */
+export declare function undoHeal(dir: string, id: string): {
+    id: string;
+    restored: string[];
+    skipped: Array<{
+        file: string;
+        why: string;
+    }>;
+};