@squidcloud/backend 1.0.482 → 1.0.484

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/dist/backend/src/actions.d.ts +14 -1
  2. package/dist/backend/src/cli-agent/claude-code.adapter.d.ts +74 -0
  3. package/dist/backend/src/cli-agent/cli-agent-adapter.types.d.ts +112 -0
  4. package/dist/backend/src/cli-agent/cli-agent-process-launcher.d.ts +22 -0
  5. package/dist/backend/src/cli-agent/cli-agent-process-runner.d.ts +35 -0
  6. package/dist/backend/src/cli-agent/codex.adapter.d.ts +67 -0
  7. package/dist/backend/src/cli-agent/index.d.ts +7 -0
  8. package/dist/backend/src/cli-agent/nsjail-source-process-launcher.d.ts +45 -0
  9. package/dist/backend/src/cli-agent/workspace.utils.d.ts +20 -0
  10. package/dist/backend/src/internal/source-code.d.ts +3 -0
  11. package/dist/backend/src/public-types.d.ts +5 -0
  12. package/dist/backend/src/source-code/index.d.ts +17 -0
  13. package/dist/backend/src/source-code/providers/bitbucket-cloud.client.d.ts +20 -0
  14. package/dist/backend/src/source-code/providers/github-app.client.d.ts +45 -0
  15. package/dist/backend/src/source-code/providers/index.d.ts +2 -0
  16. package/dist/backend/src/source-code/restricted-source-runner.d.ts +95 -0
  17. package/dist/backend/src/source-code/source-analysis-admission-controller.d.ts +35 -0
  18. package/dist/backend/src/source-code/source-code-analyzer.d.ts +60 -0
  19. package/dist/backend/src/source-code/source-code-errors.d.ts +13 -0
  20. package/dist/backend/src/source-code/source-code-limits.d.ts +33 -0
  21. package/dist/backend/src/source-code/source-code-telemetry.d.ts +35 -0
  22. package/dist/backend/src/source-code/source-egress-proxy.d.ts +123 -0
  23. package/dist/backend/src/source-code/source-evidence-verifier.d.ts +30 -0
  24. package/dist/backend/src/source-code/source-git-command.d.ts +57 -0
  25. package/dist/backend/src/source-code/source-git-credential-helper.d.ts +5 -0
  26. package/dist/backend/src/source-code/source-provider-adapter.d.ts +87 -0
  27. package/dist/backend/src/source-code/source-provider-operation-broker.d.ts +111 -0
  28. package/dist/backend/src/source-code/source-repository-snapshot.d.ts +15 -0
  29. package/dist/backend/src/source-code/source-run-filesystem.d.ts +82 -0
  30. package/dist/backend/src/source-code/source-socket-admission.d.ts +17 -0
  31. package/dist/backend/src/source-code/source-workspace-manager.d.ts +179 -0
  32. package/dist/backend/src/source-code/source-workspace-manifest.d.ts +43 -0
  33. package/dist/backend/src/squid.service.d.ts +16 -0
  34. package/dist/backend/src/workspace-client.d.ts +126 -8
  35. package/dist/cjs/index.js +1 -1
  36. package/dist/cjs/internal/source-code.js +1 -0
  37. package/dist/esm/index.js +1 -1
  38. package/dist/esm/internal/source-code.js +1 -0
  39. package/dist/internal-common/src/public-types-backend/bundle-api.public-types.d.ts +5 -0
  40. package/dist/internal-common/src/public-types-backend/bundle-data.public-types.d.ts +1 -1
  41. package/dist/internal-common/src/public-types-backend/langgraph.public-context.d.ts +16 -0
  42. package/package.json +14 -2
@@ -0,0 +1,35 @@
1
+ /** Releases one process-wide source-analysis admission slot. */
2
+ export interface SourceAnalysisAdmissionPermit {
3
+ /** Makes the slot available to the next queued analysis. */
4
+ release(): Promise<void>;
5
+ }
6
+ /** Represents the admission boundary consumed by source orchestration. */
7
+ export interface SourceAnalysisAdmissionControllerLike {
8
+ /** Waits for a bounded process-wide analysis slot. */
9
+ acquire(signal?: AbortSignal): Promise<SourceAnalysisAdmissionPermit>;
10
+ }
11
+ /** Configures the process-wide source-analysis admission boundary. */
12
+ export interface SourceAnalysisAdmissionControllerOptions {
13
+ /** Bounds simultaneous analysis filesystems in one tenant process. */
14
+ maxConcurrentAnalyses: number;
15
+ /** Bounds how long a caller waits for a slot. */
16
+ waitTimeoutMs: number;
17
+ /** Overrides the retry interval for deterministic tests. */
18
+ retryIntervalMs?: number;
19
+ /** Isolates a controller namespace for deterministic tests. */
20
+ scope?: string;
21
+ }
22
+ /**
23
+ * Uses operating-system listener ownership as a crash-safe semaphore shared by every worker thread
24
+ * in one tenant process.
25
+ */
26
+ export declare class SourceAnalysisAdmissionController implements SourceAnalysisAdmissionControllerLike {
27
+ private readonly maxConcurrentAnalyses;
28
+ private readonly retryIntervalMs;
29
+ private readonly scope;
30
+ private readonly waitTimeoutMs;
31
+ /** Creates a bounded semaphore whose slots are released automatically if their worker exits. */
32
+ constructor(options: SourceAnalysisAdmissionControllerOptions);
33
+ /** Waits until this tenant process has capacity or the bounded wait ends. */
34
+ acquire(signal?: AbortSignal): Promise<SourceAnalysisAdmissionPermit>;
35
+ }
@@ -0,0 +1,60 @@
1
+ import { type AiAgentSourceCodeIntegrationOptions, type AnalyzeCodeRequest, type AnalyzeCodeResult } from '@squidcloud/client';
2
+ import { RestrictedSourceRunRequest, RestrictedSourceRunResult } from './restricted-source-runner';
3
+ import { type SourceAnalysisAdmissionControllerLike } from './source-analysis-admission-controller';
4
+ import { SourceCodeLimits } from './source-code-limits';
5
+ import { SourceCodeTelemetry } from './source-code-telemetry';
6
+ import { SourceEvidenceVerifier } from './source-evidence-verifier';
7
+ import type { SourceProviderAdapter } from './source-provider-adapter';
8
+ import { SourceWorkspaceManager } from './source-workspace-manager';
9
+ /** Supplies one complete source-analysis request and its trusted dependencies. */
10
+ export interface SourceCodeAnalyzeInput {
11
+ /** Identifies the application making the request. */
12
+ appId: string;
13
+ /** Identifies the connected source integration. */
14
+ integrationId: string;
15
+ /** Supplies the user question and optional source hints. */
16
+ request: AnalyzeCodeRequest;
17
+ /** Configures source analysis for the connected integration. */
18
+ options: AiAgentSourceCodeIntegrationOptions;
19
+ /** Supplies integration-scoped supplemental instructions. */
20
+ connectedIntegrationInstructions?: string;
21
+ /** Supplies the exact application-owned model credential to the outer proxy. */
22
+ analyzerApiKey: string;
23
+ /** Supplies repository authorization and provider reads. */
24
+ adapter: SourceProviderAdapter;
25
+ }
26
+ /** Represents the restricted runner boundary used by orchestration tests. */
27
+ export interface RestrictedSourceRunnerLike {
28
+ /** Executes one credential-isolated analyzer request. */
29
+ run(request: RestrictedSourceRunRequest): Promise<RestrictedSourceRunResult>;
30
+ }
31
+ /** Configures testable source-analysis orchestration boundaries. */
32
+ export interface SourceCodeAnalyzerOptions {
33
+ /** Overrides process-wide source-analysis admission. */
34
+ admissionController?: SourceAnalysisAdmissionControllerLike;
35
+ /** Overrides trusted workspace preparation. */
36
+ workspaceManager?: SourceWorkspaceManager;
37
+ /** Overrides the isolated CLI runner. */
38
+ restrictedRunner?: RestrictedSourceRunnerLike;
39
+ /** Overrides strict Git provenance verification. */
40
+ evidenceVerifier?: SourceEvidenceVerifier;
41
+ /** Records bounded internal telemetry. */
42
+ telemetry?: SourceCodeTelemetry;
43
+ /** Overrides source-analysis limits. */
44
+ limits?: SourceCodeLimits;
45
+ }
46
+ /** Coordinates trusted preparation, the isolated CLI, provenance validation, and telemetry. */
47
+ export declare class SourceCodeAnalyzer {
48
+ private readonly admissionController;
49
+ private readonly evidenceVerifier;
50
+ private readonly limits;
51
+ private readonly restrictedRunner;
52
+ private readonly telemetry;
53
+ private readonly workspaceManager;
54
+ /** Creates production orchestration unless explicit test boundaries are supplied. */
55
+ constructor(options?: SourceCodeAnalyzerOptions);
56
+ /** Runs one source-code analysis and returns only provenance-validated evidence. */
57
+ analyze(input: SourceCodeAnalyzeInput): Promise<AnalyzeCodeResult>;
58
+ private recordTelemetry;
59
+ private withAdmission;
60
+ }
@@ -0,0 +1,13 @@
1
+ /** Lists stable source-analysis error categories exposed to applications. */
2
+ export declare const SOURCE_CODE_ERROR_CODES: readonly ["SOURCE_CONFIGURATION_INVALID", "SOURCE_AUTHENTICATION_FAILED", "SOURCE_REPOSITORY_UNAVAILABLE", "SOURCE_WORKSPACE_BUSY", "SOURCE_RESOURCE_LIMIT", "SOURCE_SANDBOX_UNAVAILABLE", "SOURCE_ANALYZER_TIMEOUT", "SOURCE_ANALYZER_FAILED", "SOURCE_LEASE_LOST", "SOURCE_EVIDENCE_UNVERIFIED"];
3
+ /** Identifies a stable source-analysis error category. */
4
+ export type SourceCodeErrorCode = (typeof SOURCE_CODE_ERROR_CODES)[number];
5
+ /** Carries a safe source-analysis category without provider or repository details. */
6
+ export declare class SourceCodeError extends Error {
7
+ readonly code: SourceCodeErrorCode;
8
+ readonly name = "SourceCodeError";
9
+ /** Creates a safe source-analysis error. */
10
+ constructor(code: SourceCodeErrorCode);
11
+ }
12
+ /** Converts internal failures to the stable source-analysis error surface. */
13
+ export declare function toSourceCodeError(error: unknown): SourceCodeError;
@@ -0,0 +1,33 @@
1
+ /** Configures source-code preparation, analysis, storage, and lease ceilings. */
2
+ export interface SourceCodeLimits {
3
+ /** Bounds waiting for process-wide source-analysis capacity. */
4
+ admissionWaitMs: number;
5
+ /** Bounds repositories exposed to one analyzer run. */
6
+ maxRepositories: number;
7
+ /** Bounds simultaneous source analyses in one tenant process. */
8
+ maxConcurrentAnalyses: number;
9
+ /** Bounds persistent or disposable workspace bytes. */
10
+ maxWorkspaceBytes: number;
11
+ /** Bounds inodes in the quota-backed analyzer filesystem. */
12
+ maxRunInodes: number;
13
+ /** Bounds raw analyzer stdout bytes. */
14
+ maxStdoutBytes: number;
15
+ /** Bounds combined analyzer output bytes. */
16
+ maxOutputBytes: number;
17
+ /** Bounds trusted Git preparation wall-clock duration. */
18
+ preparationTimeoutMs: number;
19
+ /** Bounds analyzer wall-clock duration. */
20
+ analyzerTimeoutMs: number;
21
+ /** Bounds cached snapshot age during transient provider failures. */
22
+ maxStaleAgeMs: number;
23
+ /** Bounds waiting for exclusive workspace ownership. */
24
+ leaseWaitMs: number;
25
+ /** Configures the exclusive workspace lease lifetime. */
26
+ leaseTtlMs: number;
27
+ /** Configures the exclusive workspace lease heartbeat interval. */
28
+ leaseHeartbeatMs: number;
29
+ }
30
+ /** Supplies the production source-code limits. */
31
+ export declare const DEFAULT_SOURCE_CODE_LIMITS: Readonly<SourceCodeLimits>;
32
+ /** Resolves and validates deployment source-code limits. */
33
+ export declare function resolveSourceCodeLimits(environment?: Readonly<Record<string, string | undefined>>): SourceCodeLimits;
@@ -0,0 +1,35 @@
1
+ import type { SourceCodeAnalyzerModel, SourceControlProvider } from '@squidcloud/client';
2
+ /** Lists bounded source-analysis outcomes. */
3
+ export type SourceCodeOutcome = 'success' | 'stale-success' | 'persistence-warning' | 'configuration' | 'authentication' | 'repository-unavailable' | 'workspace-busy' | 'resource-limit' | 'sandbox-unavailable' | 'analyzer-timeout' | 'analyzer-failed' | 'lease-lost' | 'evidence-unverified';
4
+ /** Contains source-analysis metrics without repository or question content. */
5
+ export interface SourceCodeTelemetryEvent {
6
+ /** Identifies the source-control provider. */
7
+ provider: SourceControlProvider;
8
+ /** Identifies the isolated CLI analyzer. */
9
+ analyzerModel: SourceCodeAnalyzerModel;
10
+ /** Categorizes the bounded analysis result. */
11
+ outcome: SourceCodeOutcome;
12
+ /** Counts repositories exposed to the analyzer. */
13
+ repositoryCount: number;
14
+ /** Describes whether trusted caches were created or reused. */
15
+ cacheState: 'first-clone' | 'reused' | 'mixed';
16
+ /** Marks whether any analyzed snapshot was stale. */
17
+ stale: boolean;
18
+ /** Marks whether exclusive workspace ownership was lost. */
19
+ leaseLost: boolean;
20
+ /** Measures total analysis wall-clock duration. */
21
+ analysisDurationMs: number;
22
+ /** Measures time spent acquiring the workspace lease. */
23
+ leaseWaitMs: number;
24
+ /** Measures trusted workspace bytes after preparation. */
25
+ workspaceBytes: number;
26
+ /** Counts model input tokens when reported by the CLI. */
27
+ inputTokens: number;
28
+ /** Counts model output tokens when reported by the CLI. */
29
+ outputTokens: number;
30
+ }
31
+ /** Records bounded source-analysis telemetry. */
32
+ export interface SourceCodeTelemetry {
33
+ /** Records one completed source-analysis attempt. */
34
+ record(event: SourceCodeTelemetryEvent): void;
35
+ }
@@ -0,0 +1,123 @@
1
+ import { SourceCodeAnalyzerModel } from '@squidcloud/client';
2
+ import { IncomingHttpHeaders } from 'node:http';
3
+ import { Readable, Writable } from 'node:stream';
4
+ interface SourceModelAuthProxyDependencies {
5
+ lookup(host: string, signal: AbortSignal): Promise<Array<{
6
+ address: string;
7
+ family: number;
8
+ }>>;
9
+ send(input: UpstreamRequest): Promise<UpstreamResponse>;
10
+ }
11
+ /** Describes one fixed model API route selected by trusted configuration. */
12
+ export interface SourceModelProxyRoute {
13
+ /** Selects the fixed upstream model host. */
14
+ host: string;
15
+ /** Selects the fixed upstream HTTP method. */
16
+ method: 'HEAD' | 'POST';
17
+ /** Selects the fixed upstream path and query. */
18
+ path: string;
19
+ }
20
+ /** Configures the trusted reverse proxy for one selected analyzer model. */
21
+ export interface SourceModelAuthProxyOptions {
22
+ /** Selects the model-specific route allowlist. */
23
+ analyzerModel: SourceCodeAnalyzerModel;
24
+ /** Supplies the real credential retained outside the jail. */
25
+ apiKey: string;
26
+ }
27
+ /** Defines aggregate ceilings shared by every model request in one source run. */
28
+ export interface SourceModelProxyBudgetLimits {
29
+ /** Bounds all provider output tokens reported or reserved by the run. */
30
+ maxCumulativeOutputTokens: number;
31
+ /** Bounds all primary request bytes accepted by the proxy. */
32
+ maxCumulativeRequestBytes: number;
33
+ /** Bounds all upstream response body bytes accepted by the proxy. */
34
+ maxCumulativeResponseBytes: number;
35
+ /** Bounds the output-token parameter on one primary request. */
36
+ maxOutputTokensPerRequest: number;
37
+ /** Bounds all allowed model endpoint operations. */
38
+ maxRequests: number;
39
+ }
40
+ interface PreparedSourceModelProxyRequest {
41
+ body: Buffer;
42
+ reservation: SourceModelProxyTokenReservation;
43
+ }
44
+ declare class SourceModelProxyTokenReservation {
45
+ readonly maximumOutputTokens: number;
46
+ settled: boolean;
47
+ constructor(maximumOutputTokens: number);
48
+ }
49
+ /** Accounts for aggregate model operations and binds one immutable provider wire model per run. */
50
+ export declare class SourceModelProxyRunBudget {
51
+ private boundWireModel;
52
+ private consumedOutputTokens;
53
+ private requestBytes;
54
+ private requestCount;
55
+ private reservedOutputTokens;
56
+ private responseBytes;
57
+ private readonly limits;
58
+ /** Creates a budget with production ceilings unless trusted overrides are supplied. */
59
+ constructor(overrides?: Partial<SourceModelProxyBudgetLimits>);
60
+ /** Consumes one endpoint operation from the run-wide request budget. */
61
+ beginRequest(): void;
62
+ /** Consumes accepted primary request bytes from the run-wide byte budget. */
63
+ recordRequestBytes(bytes: number): void;
64
+ /** Consumes upstream response bytes from the run-wide byte budget. */
65
+ recordResponseBytes(bytes: number): void;
66
+ /**
67
+ * Validates one primary request, binds the first valid CLI wire model, and reserves its bounded
68
+ * output allowance. The primary CLI reaches this request before repository content can direct a
69
+ * later tool call, and JavaScript performs the binding and comparison as one synchronous action.
70
+ */
71
+ preparePrimaryRequest(analyzerModel: SourceCodeAnalyzerModel, rawBody: Buffer): PreparedSourceModelProxyRequest;
72
+ /** Replaces a request's reservation with trusted provider-reported output usage. */
73
+ completePrimaryRequest(reservation: SourceModelProxyTokenReservation, reportedOutputTokens: number | undefined): void;
74
+ }
75
+ /** Owns the real model key and forwards only version-tested model API calls. */
76
+ export declare class SourceModelAuthProxy {
77
+ private readonly options;
78
+ private readonly dependencies;
79
+ private activeRequests;
80
+ private readonly budget;
81
+ private closePromise;
82
+ private closing;
83
+ private lifecycleController;
84
+ private readonly pendingHandlers;
85
+ private server;
86
+ private readonly socketAdmission;
87
+ private socketPath;
88
+ /** Creates a proxy for exactly one model provider and credential. */
89
+ constructor(options: SourceModelAuthProxyOptions, dependencies?: SourceModelAuthProxyDependencies);
90
+ /** Starts the proxy on a private Unix socket. */
91
+ start(socketPath: string): Promise<void>;
92
+ /** Stops the proxy and removes its private socket. */
93
+ close(): Promise<void>;
94
+ private closeInternal;
95
+ private handleRequest;
96
+ }
97
+ /** Resolves one allowed loopback request to its fixed upstream model route. */
98
+ export declare function resolveSourceModelProxyRoute(analyzerModel: SourceCodeAnalyzerModel, method: string | undefined, requestUrl: string | undefined, headers: IncomingHttpHeaders): SourceModelProxyRoute;
99
+ /** Streams a proxy body while enforcing its byte ceiling. */
100
+ export declare function pipeSourceModelProxyBody(source: Readable, destination: Writable, maxBytes: number, limitError: string, signal?: AbortSignal, observeChunk?: (chunk: Buffer) => void): Promise<number>;
101
+ /** Extracts the greatest cumulative output-token usage reported by one provider response. */
102
+ export declare function extractSourceModelProxyOutputTokens(analyzerModel: SourceCodeAnalyzerModel, body: Buffer): number | undefined;
103
+ interface UpstreamRequest {
104
+ address: string;
105
+ apiKey: string;
106
+ body: Readable;
107
+ family: number;
108
+ headers: IncomingHttpHeaders;
109
+ host: string;
110
+ method: 'HEAD' | 'POST';
111
+ model: SourceCodeAnalyzerModel;
112
+ path: string;
113
+ signal: AbortSignal;
114
+ }
115
+ interface UpstreamResponse {
116
+ statusCode: number;
117
+ headers: IncomingHttpHeaders;
118
+ body: Readable;
119
+ requestCompleted: Promise<number>;
120
+ }
121
+ /** Returns true only for addresses safe to use as fixed public model-provider destinations. */
122
+ export declare function isPublicAddress(address: string): boolean;
123
+ export {};
@@ -0,0 +1,30 @@
1
+ import type { AnalyzeCodeResult } from '@squidcloud/client';
2
+ import { SourceGitCommand } from './source-git-command';
3
+ import type { PreparedSourceWorkspace } from './source-workspace-manager';
4
+ /** Supplies trusted state and one bounded analyzer response for verification. */
5
+ export interface VerifySourceEvidenceInput {
6
+ /** Contains exactly one analyzer JSON object. */
7
+ analyzerResponse: string;
8
+ /** Supplies pre-run refs and trusted bare repositories. */
9
+ preparedWorkspace: PreparedSourceWorkspace;
10
+ }
11
+ /** Configures the local Git boundary used for provenance validation. */
12
+ export interface SourceEvidenceVerifierOptions {
13
+ /** Overrides hardened Git execution. */
14
+ gitCommand?: SourceGitCommand;
15
+ }
16
+ /** Strictly parses analyzer output and retains only evidence proven by trusted Git objects. */
17
+ export declare class SourceEvidenceVerifier {
18
+ private readonly git;
19
+ /** Creates a verifier with ambient Git configuration disabled. */
20
+ constructor(options?: SourceEvidenceVerifierOptions);
21
+ /** Returns structured provenance only when at least one regular trusted blob is valid. */
22
+ verify(input: VerifySourceEvidenceInput): Promise<AnalyzeCodeResult>;
23
+ private verifyRepository;
24
+ private verifySubmodule;
25
+ private verifyPreparedSource;
26
+ private assertCommitExists;
27
+ private verifyRef;
28
+ private verifyPath;
29
+ private readBlob;
30
+ }
@@ -0,0 +1,57 @@
1
+ /** Classifies a failed trusted Git operation without retaining sensitive stderr. */
2
+ export type SourceGitFailureKind = 'authentication' | 'repository-unavailable' | 'transient' | 'resource-limit' | 'aborted';
3
+ /** Carries a bounded trusted Git failure category. */
4
+ export declare class SourceGitCommandError extends Error {
5
+ readonly kind: SourceGitFailureKind;
6
+ readonly name = "SourceGitCommandError";
7
+ /** Creates a Git error that contains no command, URL, repository, or credential. */
8
+ constructor(kind: SourceGitFailureKind);
9
+ }
10
+ /** Selects the protocol policy for one trusted Git command. */
11
+ export type SourceGitCommandMode = 'local' | 'remote';
12
+ /** Configures one hardened trusted Git child. */
13
+ export interface SourceGitCommandOptions {
14
+ /** Selects the fixed local or remote protocol policy. */
15
+ mode: SourceGitCommandMode;
16
+ /** Supplies a synthesized credential or TLS environment. */
17
+ environment?: Readonly<NodeJS.ProcessEnv>;
18
+ /** Selects the child working directory. */
19
+ cwd?: string;
20
+ /** Supplies bounded stdin for plumbing commands. */
21
+ input?: Buffer;
22
+ /** Aborts the complete Git child. */
23
+ signal?: AbortSignal;
24
+ /** Bounds child wall-clock duration. */
25
+ timeoutMs: number;
26
+ /** Bounds combined stdout and stderr bytes. */
27
+ maxOutputBytes?: number;
28
+ /** Bounds any single file written by a remote Git child on Linux. */
29
+ maxFileBytes?: number;
30
+ }
31
+ /** Contains bounded stdout from a successful trusted Git command. */
32
+ export interface SourceGitCommandResult {
33
+ /** Stores raw stdout bytes for exact Git protocol parsing. */
34
+ stdout: Buffer;
35
+ }
36
+ /** Describes the executable and arguments used for one hardened Git child. */
37
+ export interface SourceGitInvocation {
38
+ /** Supplies the complete fixed and caller-provided argument array. */
39
+ arguments: readonly string[];
40
+ /** Identifies the absolute production executable. */
41
+ executable: string;
42
+ }
43
+ /** Runs Git through a single command-array boundary with ambient configuration disabled. */
44
+ export declare class SourceGitCommand {
45
+ private readonly runtimeRootDirectory;
46
+ private readonly executable;
47
+ private readonly fileLimitExecutable;
48
+ /** Creates a hardened Git boundary rooted in a private empty hooks directory. */
49
+ constructor(runtimeRootDirectory: string, executable?: string, fileLimitExecutable?: string | undefined);
50
+ /** Runs one fixed-argument Git command and returns bounded raw stdout. */
51
+ run(args: readonly string[], options: SourceGitCommandOptions): Promise<SourceGitCommandResult>;
52
+ private fixedArguments;
53
+ }
54
+ /** Builds a minimal Git environment without ambient credential controls. */
55
+ export declare function buildSourceGitEnvironment(source: Readonly<NodeJS.ProcessEnv> | undefined, ambient?: Readonly<NodeJS.ProcessEnv>, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
56
+ /** Wraps Git with a kernel-enforced file-size limit on Linux. */
57
+ export declare function buildSourceGitInvocation(gitExecutable: string, gitArguments: readonly string[], maxFileBytes: number | undefined, platform?: NodeJS.Platform, fileLimitExecutable?: string | undefined): SourceGitInvocation;
@@ -0,0 +1,5 @@
1
+ /** Creates an ephemeral Git credential boundary for trusted preparation commands. */
2
+ export declare class SourceGitCredentialHelper {
3
+ /** Runs an operation with credentials available only to its direct Git child. */
4
+ withEnvironment<T>(username: string, password: string, operation: (environment: NodeJS.ProcessEnv) => Promise<T>): Promise<T>;
5
+ }
@@ -0,0 +1,87 @@
1
+ import type { IntegrationInfo, SourceCodeIntegrationType, SourceControlProvider, SourceRepository } from '@squidcloud/client';
2
+ /** Lists provider permissions available to source-code orchestration. */
3
+ export type SourceProviderPermission = 'contents:read' | 'metadata:read' | 'contents:write' | 'pull-requests:read' | 'pull-requests:write';
4
+ /** Categorizes provider failures without exposing response bodies or credentials. */
5
+ export type SourceProviderFailureClassification = 'transient' | 'authentication' | 'repository-unavailable' | 'resource-limit' | 'aborted';
6
+ /** Carries a bounded provider failure category and safe provider code. */
7
+ export declare class SourceProviderError extends Error {
8
+ readonly classification: SourceProviderFailureClassification;
9
+ readonly name = "SourceProviderError";
10
+ /** Creates a provider error safe for trusted failure classification. */
11
+ constructor(classification: SourceProviderFailureClassification, code: string);
12
+ }
13
+ /** Narrows provider credentials to repositories and operations. */
14
+ export interface SourceCredentialScope {
15
+ /** Lists repositories available to the credential. */
16
+ repositories: readonly SourceRepository[];
17
+ /** Lists operations available to the credential. */
18
+ permissions: readonly SourceProviderPermission[];
19
+ }
20
+ /** Contains noninteractive HTTPS credentials for one trusted Git operation. */
21
+ export interface SourceGitCredential {
22
+ /** Supplies the provider-defined Git username. */
23
+ username: string;
24
+ /** Supplies the provider credential. */
25
+ password: string;
26
+ }
27
+ /** Supplies a disposable credential to the trusted Git preparation process. */
28
+ export interface SourcePreparationCredentials {
29
+ /** Supplies noninteractive HTTPS Git authentication. */
30
+ gitCredential: SourceGitCredential;
31
+ /** Marks when the provider credential expires. */
32
+ expiresAt?: string;
33
+ }
34
+ /** Identifies one repository selected in integration configuration without provider I/O. */
35
+ export interface SourceConfiguredRepository {
36
+ /** Supplies the canonical owner and repository name. */
37
+ fullName: string;
38
+ /** Supplies the immutable provider identity when the integration format stores it. */
39
+ providerRepositoryId?: string;
40
+ }
41
+ /** Describes provider-native reads available through the trusted broker. */
42
+ export type SourceProviderReadOperation = {
43
+ type: 'repository-view';
44
+ repository: string;
45
+ } | {
46
+ type: 'pull-request-view';
47
+ repository: string;
48
+ number: number;
49
+ } | {
50
+ type: 'pull-request-list';
51
+ repository: string;
52
+ state: 'open' | 'closed' | 'all';
53
+ limit: number;
54
+ };
55
+ /** Isolates source-provider authentication and native operations from orchestration. */
56
+ export interface SourceProviderAdapter {
57
+ /** Identifies the provider. */
58
+ readonly provider: SourceControlProvider;
59
+ /** Returns the repository selection stored in the current integration configuration. */
60
+ getConfiguredRepositories(): readonly SourceConfiguredRepository[];
61
+ /** Returns the canonical application allowlist. */
62
+ getAllowedRepositories(signal: AbortSignal): Promise<readonly SourceRepository[]>;
63
+ /** Creates credentials for trusted Git preparation only. */
64
+ createPreparationCredentials(scope: SourceCredentialScope, signal: AbortSignal): Promise<SourcePreparationCredentials>;
65
+ /** Executes one provider-native read through the trusted broker. */
66
+ executeReadOperation(operation: SourceProviderReadOperation, signal: AbortSignal): Promise<unknown>;
67
+ /** Returns fixed provider instructions from the prompt registry. */
68
+ getCliInstructions(): string;
69
+ }
70
+ /** Supplies trusted Git-specific TLS material only around trusted Git children. */
71
+ export interface TrustedGitTlsProvider {
72
+ /** Runs one operation with a temporary trusted Git environment. */
73
+ runWithEnvironment<T>(run: (environment: Readonly<Record<string, string>>) => Promise<T>): Promise<T>;
74
+ }
75
+ /** Supplies app-scoped provider configuration and secret resolution. */
76
+ export interface SourceProviderFactoryContext {
77
+ /** Identifies the integration. */
78
+ integrationId: string;
79
+ /** Identifies the provider integration type. */
80
+ integrationType: SourceCodeIntegrationType;
81
+ /** Supplies the canonical integration configuration. */
82
+ integration: IntegrationInfo;
83
+ /** Resolves an app-owned secret reference. */
84
+ resolveSecret(secretName: string): Promise<string>;
85
+ }
86
+ /** Constructs one provider adapter for a connected integration. */
87
+ export type SourceProviderFactory = (context: SourceProviderFactoryContext) => Promise<SourceProviderAdapter>;
@@ -0,0 +1,111 @@
1
+ import { SourceControlProvider } from '@squidcloud/client';
2
+ /** Identifies the deterministic provider-shim protocol. */
3
+ export declare const SOURCE_PROVIDER_BROKER_PROTOCOL_VERSION: 1;
4
+ /** Describes the closed provider-operation subset exposed to source analyzers. */
5
+ export type SourceProviderOperation = {
6
+ operation: 'repo-view';
7
+ repository: string;
8
+ } | {
9
+ operation: 'pr-view';
10
+ repository: string;
11
+ pullRequestNumber: number;
12
+ } | {
13
+ operation: 'pr-list';
14
+ repository: string;
15
+ state: 'open' | 'closed' | 'all';
16
+ limit: number;
17
+ };
18
+ /** Executes provider reads after the broker validates protocol, authorization, and budgets. */
19
+ export interface SourceProviderReadAdapter {
20
+ /** Identifies the adapter's source-control provider. */
21
+ readonly provider: SourceControlProvider;
22
+ /** Executes one already-authorized typed read. */
23
+ executeReadOperation(operation: SourceProviderOperation, signal: AbortSignal): Promise<unknown>;
24
+ /** Releases adapter child processes and credentials. */
25
+ close(): Promise<void>;
26
+ }
27
+ /** Bounds all provider use during one analyzer run. */
28
+ export interface SourceProviderBrokerBudgets {
29
+ /** Bounds the number of operations in one run. */
30
+ maxOperations: number;
31
+ /** Bounds encoded response bytes across the run. */
32
+ maxCumulativeResponseBytes: number;
33
+ /** Bounds simultaneous provider operations. */
34
+ maxConcurrentRequests: number;
35
+ /** Bounds total broker lifetime. */
36
+ maxElapsedMs: number;
37
+ /** Bounds estimated provider rate-limit consumption. */
38
+ maxProviderRateUnits: number;
39
+ /** Bounds one encoded response frame. */
40
+ maxResponseBytes: number;
41
+ /** Bounds one provider operation. */
42
+ requestDeadlineMs: number;
43
+ }
44
+ /** Configures one provider-neutral operation broker. */
45
+ export interface SourceProviderOperationBrokerOptions {
46
+ /** Supplies the credential-owning provider adapter. */
47
+ adapter: SourceProviderReadAdapter;
48
+ /** Lists the case-folded repository identities available to the run. */
49
+ allowedRepositories: readonly string[];
50
+ /** Overrides per-run broker budgets. */
51
+ budgets?: Partial<SourceProviderBrokerBudgets>;
52
+ }
53
+ /** Validates and budgets provider reads over a strict framed Unix-socket protocol. */
54
+ export declare class SourceProviderOperationBroker {
55
+ private readonly options;
56
+ private readonly allowedRepositories;
57
+ private readonly activeControllers;
58
+ private readonly budgets;
59
+ private readonly inFlightHandlers;
60
+ private readonly socketAdmission;
61
+ private readonly startedAt;
62
+ private activeRequests;
63
+ private closing;
64
+ private cumulativeResponseBytes;
65
+ private operationCount;
66
+ private providerRateUnits;
67
+ private server;
68
+ private socketPath;
69
+ /** Creates a broker for one provider adapter and repository allowlist. */
70
+ constructor(options: SourceProviderOperationBrokerOptions);
71
+ /** Starts the versioned framed protocol on a private Unix socket. */
72
+ start(socketPath: string): Promise<void>;
73
+ /** Stops accepting operations, closes connections, and drains the provider adapter. */
74
+ close(): Promise<void>;
75
+ /** Executes one already-decoded operation through the same authorization and budget boundary. */
76
+ execute(operation: SourceProviderOperation): Promise<unknown>;
77
+ private acceptSocket;
78
+ private handleFrame;
79
+ private writeErrorAndClose;
80
+ private validateOperation;
81
+ private reserveOperation;
82
+ private remainingElapsedMillis;
83
+ }
84
+ /** Executes GitHub reads with a short-lived credential and fixed host gh arguments. */
85
+ export declare class GitHubCliReadAdapter implements SourceProviderReadAdapter {
86
+ private readonly options;
87
+ readonly provider = "github";
88
+ private readonly activeChildren;
89
+ private closing;
90
+ /** Creates the GitHub adapter around an absolute, version-pinned gh executable. */
91
+ constructor(options: {
92
+ executable: string;
93
+ credentialProvider(): Promise<string>;
94
+ commandTimeoutMs?: number;
95
+ });
96
+ /** Executes one fixed GitHub read and returns parsed JSON. */
97
+ executeReadOperation(operation: SourceProviderOperation, signal: AbortSignal): Promise<unknown>;
98
+ /** Terminates active gh children and waits for their complete stream closure. */
99
+ close(): Promise<void>;
100
+ private run;
101
+ }
102
+ /** Provides an immediate typed failure while cached analysis has no live provider authorization. */
103
+ export declare class UnavailableSourceProviderReadAdapter implements SourceProviderReadAdapter {
104
+ readonly provider: SourceControlProvider;
105
+ /** Creates an unavailable adapter for one provider. */
106
+ constructor(provider: SourceControlProvider);
107
+ /** Rejects immediately without opening a child process. */
108
+ executeReadOperation(_operation: SourceProviderOperation, _signal: AbortSignal): Promise<never>;
109
+ /** Completes without external resources. */
110
+ close(): Promise<void>;
111
+ }
@@ -0,0 +1,15 @@
1
+ /** Captures trusted references before the analyzer can mutate its disposable copy. */
2
+ export interface SourceRepositorySnapshot {
3
+ /** Points to the trusted bare repository outside the analyzer mount. */
4
+ trustedRepositoryDirectory: string;
5
+ /** Maps canonical remote-branch and tag refs to commit SHAs. */
6
+ refs: ReadonlyMap<string, string>;
7
+ /** Stores the selected canonical default ref. */
8
+ defaultRef: string;
9
+ /** Stores the selected immutable commit SHA. */
10
+ defaultCommitSha: string;
11
+ /** Stores the last successful fetch time. */
12
+ fetchedAt: string;
13
+ /** Marks a transiently stale snapshot. */
14
+ stale: boolean;
15
+ }