arc-1 0.9.18 → 0.9.20

package/dist/public/index.d.ts

@@ -0,0 +1,9 @@
+export { AdtApiError, AdtNetworkError, AdtSafetyError } from '../adt/errors.js';
+export type { AdtResponse } from '../adt/http.js';
+export { OperationType, type OperationTypeCode } from '../adt/safety.js';
+export type { Scope } from '../authz/policy.js';
+export type { ToolResult } from '../registry/tool-registry.js';
+export type { SafeHttpClient } from '../server/safe-http-client.js';
+export { defineTool } from './define-tool.js';
+export type { ElicitOutcome, Plugin, PluginLogger, PluginToolDefinition, ReadOnlyAdtClient, ToolContext, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/public/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/public/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACzE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EACV,aAAa,EACb,MAAM,EACN,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/public/index.js

@@ -0,0 +1,10 @@
+// `arc-1/public` — the @experimental extension API surface.
+//
+// Stability: this API may break in ANY release. A plugin declares `apiVersion` (a single integer
+// fuse); the loader rejects a mismatch. No semver guarantee until the feature graduates.
+// See docs/research/extension-framework-spec.md §2.
+export { AdtApiError, AdtNetworkError, AdtSafetyError } from '../adt/errors.js';
+// Re-exported building blocks (stable shapes plugins reference):
+export { OperationType } from '../adt/safety.js';
+export { defineTool } from './define-tool.js';
+//# sourceMappingURL=index.js.map

package/dist/public/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/public/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,iGAAiG;AACjG,yFAAyF;AACzF,oDAAoD;AAEpD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGhF,iEAAiE;AACjE,OAAO,EAAE,aAAa,EAA0B,MAAM,kBAAkB,CAAC;AAIzE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/public/testing.d.ts

@@ -0,0 +1,27 @@
+import type { ToolContext } from './types.js';
+export interface MockHttpCall {
+    method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    body?: string;
+}
+export interface MockToolContext extends ToolContext {
+    /** Every `ctx.http` call the handler made, in order. */
+    httpCalls: MockHttpCall[];
+    /** Every class name passed to `ctx.run.classRun`, in order. */
+    classRunCalls: string[];
+}
+export interface MockToolContextOptions {
+    /** Body returned by every `ctx.http` call (unless overridden per-path by `responses`). */
+    responseBody?: string;
+    /** Per-path response bodies; falls back to `responseBody` then ''. */
+    responses?: Record<string, string>;
+    /** Scopes on `ctx.authInfo` (default `['read']`). */
+    scopes?: string[];
+    requestId?: string;
+    /** Partial `ctx.client` for handlers that call high-level read methods. */
+    client?: Partial<ToolContext['client']>;
+    /** Console output returned by `ctx.run.classRun` (default ''). The mock never gates. */
+    classRunOutput?: string;
+}
+export declare function createMockToolContext(options?: MockToolContextOptions): MockToolContext;
+//# sourceMappingURL=testing.d.ts.map

package/dist/public/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/public/testing.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,wDAAwD;IACxD,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAgD3F"}

package/dist/public/testing.js

@@ -0,0 +1,52 @@
+// arc-1/public/testing — helpers for unit-testing a plugin tool with no live SAP. @experimental.
+//
+// `createMockToolContext` returns a ToolContext whose `http` records every call and returns a
+// configurable body, so a plugin author can assert "my handler GETs /sap/bc/adt/… and shapes the
+// response like X" without a server. See docs/research/extension-framework-spec.md §2/§12.
+export function createMockToolContext(options = {}) {
+    const httpCalls = [];
+    const bodyFor = (path) => options.responses?.[path] ?? options.responseBody ?? '';
+    const resp = (path) => ({ statusCode: 200, headers: {}, body: bodyFor(path) });
+    // A pure recorder — never gates (the gate is unit-tested against the real createSafeHttpClient).
+    const http = {
+        get: async (path) => {
+            httpCalls.push({ method: 'GET', path });
+            return resp(path);
+        },
+        head: async (path) => {
+            httpCalls.push({ method: 'HEAD', path });
+            return resp(path);
+        },
+        post: async (path, body) => {
+            httpCalls.push({ method: 'POST', path, body });
+            return resp(path);
+        },
+        put: async (path, body) => {
+            httpCalls.push({ method: 'PUT', path, body });
+            return resp(path);
+        },
+        delete: async (path) => {
+            httpCalls.push({ method: 'DELETE', path });
+            return resp(path);
+        },
+    };
+    const classRunCalls = [];
+    const run = {
+        classRun: async (className) => {
+            classRunCalls.push(className);
+            return options.classRunOutput ?? '';
+        },
+    };
+    const ctx = {
+        client: (options.client ?? {}),
+        http,
+        run,
+        logger: { info: () => { }, warn: () => { }, error: () => { } },
+        authInfo: { userName: 'test-user', scopes: options.scopes ?? ['read'], clientId: 'test' },
+        requestId: options.requestId ?? 'test-request',
+        httpCalls,
+        classRunCalls,
+    };
+    return ctx;
+}
+//# sourceMappingURL=testing.js.map

package/dist/public/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/public/testing.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,EAAE;AACF,8FAA8F;AAC9F,iGAAiG;AACjG,2FAA2F;AAiC3F,MAAM,UAAU,qBAAqB,CAAC,UAAkC,EAAE;IACxE,MAAM,SAAS,GAAmB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAClG,MAAM,IAAI,GAAG,CAAC,IAAY,EAAe,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEpG,iGAAiG;IACjG,MAAM,IAAI,GAAmB;QAC3B,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAClB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACxC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACnB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YACzB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YACxB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACrB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;KACF,CAAC;IAEF,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,MAAM,GAAG,GAAuB;QAC9B,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;YAC5B,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,OAAO,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC;QACtC,CAAC;KACF,CAAC;IAEF,MAAM,GAAG,GAAoB;QAC3B,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAqC;QAClE,IAAI;QACJ,GAAG;QACH,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE;QAC3D,QAAQ,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE;QACzF,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,cAAc;QAC9C,SAAS;QACT,aAAa;KACd,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/public/types.d.ts

@@ -0,0 +1,87 @@
+import type { ZodTypeAny } from 'zod';
+import type { AdtClient } from '../adt/client.js';
+import type { OperationTypeCode } from '../adt/safety.js';
+import type { Scope } from '../authz/policy.js';
+import type { ToolResult } from '../registry/tool-registry.js';
+import type { SafeHttpClient } from '../server/safe-http-client.js';
+export type { SafeHttpClient, Scope, ToolResult };
+/**
+ * `AdtClient` narrowed to its safe **plain-read** facade. Omits (review B1 + post-merge review):
+ *  - `http`            — the raw, UNGATED AdtHttpClient (all HTTP must go through `ctx.http`)
+ *  - `safety`/`withSafety` — the safety ref + the escalation hatch
+ *  - the package-hierarchy cache mutators
+ *  - `getTableContents`/`runQuery`/`runTableQuery` — the **scope-escalating** reads (they gate on
+ *    `data`/`sql`, not `read`); a `read`-declared plugin must not reach them. v1 plugins have no
+ *    data/SQL surface; a scoped `ctx.data`/`ctx.sql` facade is a v2 item.
+ * Every retained method gates on `read` via `checkOperation`, so exposing them is safe. Enforced at
+ * RUNTIME too — see `createReadOnlyAdtClient` (the type Omit alone is not a security boundary).
+ */
+export type ReadOnlyAdtClient = Omit<AdtClient, 'http' | 'safety' | 'withSafety' | 'getPackageHierarchyResolver' | 'invalidatePackageHierarchy' | 'getTableContents' | 'runQuery' | 'runTableQuery'>;
+/**
+ * Named, privileged operations a plugin can invoke (e.g. executing a console class). Each op is
+ * gated server-side; calling one when its gate is closed throws `AdtSafetyError`.
+ */
+export interface PluginRunOps {
+    /**
+     * Run an ABAP **console class** (one implementing `IF_OO_ADT_CLASSRUN`) and return its console
+     * output (`out->write( … )`) as plain text. Wraps `POST /sap/bc/adt/oo/classrun/{class}`.
+     *
+     * Gated (all must hold): the server opt-in `SAP_ALLOW_PLUGIN_EXECUTE=true`, `SAP_ALLOW_WRITES=true`
+     * (executing ABAP is a mutation vector), and the calling tool must declare `write` scope. SAP-side
+     * the user still needs execute authorization. The class name is validated (no path injection).
+     */
+    classRun(className: string): Promise<string>;
+}
+/** Minimal structured logger handed to plugins (stderr only — never `console.log`). */
+export interface PluginLogger {
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/** Per-call context a plugin tool receives. Built fresh per request (never bound at registration). */
+export interface ToolContext {
+    readonly client: ReadOnlyAdtClient;
+    readonly http: SafeHttpClient;
+    readonly run: PluginRunOps;
+    readonly logger: PluginLogger;
+    readonly authInfo?: {
+        userName?: string;
+        scopes: string[];
+        clientId?: string;
+    };
+    readonly requestId: string;
+    /** Ask the user for input mid-tool (elicitation). `requestedSchema` defaults to a confirm. */
+    readonly elicit?: (message: string, requestedSchema?: Record<string, unknown>) => Promise<ElicitOutcome>;
+    /** Send a client-visible progress/log line (distinct from the stderr `logger`). */
+    readonly notify?: (level: 'info' | 'warning' | 'error', message: string) => Promise<void>;
+    /** Ask the LLM a sub-question (sampling). Returns the text answer. */
+    readonly sampling?: (systemPrompt: string, userMessage: string, maxTokens?: number) => Promise<string>;
+}
+/** The outcome of `ctx.elicit` — the MCP elicitation result. */
+export interface ElicitOutcome {
+    action: 'accept' | 'decline' | 'cancel';
+    content?: Record<string, unknown>;
+}
+/** A plugin tool definition (code tier). Named to avoid colliding with the internal MCP ToolDefinition. */
+export interface PluginToolDefinition {
+    readonly name: `Custom_${string}`;
+    readonly description: string;
+    readonly schema: ZodTypeAny;
+    readonly policy: {
+        scope: Scope;
+        opType: OperationTypeCode;
+    };
+    /** System-type visibility, enforced in `tools/list`: a non-`all` tool is hidden when the resolved
+     *  system type is known and differs (e.g. `btp` tool on an on-prem system). Default `all`. */
+    readonly availableOn?: 'all' | 'onprem' | 'btp';
+    handler(args: unknown, ctx: ToolContext): Promise<ToolResult>;
+}
+/** The default export shape of an `ARC1_PLUGINS` code plugin. */
+export interface Plugin {
+    readonly name: string;
+    readonly version: string;
+    readonly apiVersion: number;
+    readonly tools: PluginToolDefinition[];
+    readonly manifests?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/public/types.d.ts.map

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

package/dist/public/types.js

@@ -0,0 +1,4 @@
+// Public extension API types (@experimental — may break in any release; gated by `apiVersion`).
+// See docs/research/extension-framework-spec.md §2.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/public/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/public/types.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,oDAAoD"}