@patimweb/pi-abap-fs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Patrick Weppelmann
+
+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.

package/README.md

@@ -0,0 +1,101 @@
+# pi ABAP FS
+
+An [ABAP remote filesystem](https://github.com/marcellourbani/vscode_abap_remote_fs)-style
+extension for the [pi coding agent](https://github.com/earendil-works/pi-coding-agent).
+
+It gives the pi agent **live access to an SAP system** via the ADT (ABAP Development
+Tools) protocol: search and read real objects, edit and activate source code, run ABAP
+unit tests, and query live tables — all through plain-language prompts.
+
+This is a port of the core `vscode_abap_remote_fs` capabilities to pi. It is built on
+[`abap-adt-api`](https://www.npmjs.com/package/abap-adt-api), the same ADT client
+library the VS Code extension uses.
+
+## Requirements
+
+- pi coding agent (Node 26+)
+- An SAP system with **ADT (ABAP Development Tools) enabled**
+  - Reading/browsing works on NetWeaver 7.51+; writing on older systems may need the
+    `abapfs_extensions` plugin (see upstream docs).
+
+## Installation
+
+```bash
+pi install npm:@patimweb/pi-abap-fs
+```
+
+or run directly for a quick test:
+
+```bash
+pi -e ./index.ts
+```
+
+## Setup
+
+1. Ask pi to configure a connection, or call the tool directly:
+
+   ```
+   Use abap_setup to configure my dev system:
+   name=dev, url=http://vhcalnplci.bti.local:8000,
+   username=DEVELOPER, password=..., client=001
+   ```
+
+   Credentials are stored in `~/.pi/abap-config.json` (mode `0600`, owner-readable only).
+
+2. Verify the connection:
+
+   ```
+   Use abap_test_connection to check the dev profile.
+   ```
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `abap_setup` | Configure an SAP connection profile |
+| `abap_status` | Show configured profiles and the active one |
+| `abap_profile` | List / switch / delete profiles |
+| `abap_test_connection` | Verify a profile can log on |
+| `abap_search` | Search objects by name pattern |
+| `abap_object_structure` | Object metadata and include list |
+| `abap_read` | Read an object's source code |
+| `abap_lock` / `abap_unlock` | Lock management |
+| `abap_write` | Write source code (lock → write → unlock) |
+| `abap_activate` | Activate an object |
+| `abap_syntax_check` | Syntax-check source |
+| `abap_unit_test` | Run ABAP unit tests |
+| `abap_query` | Run an ABAP SQL query |
+| `abap_table` | Preview table/view contents |
+| `abap_where_used` | Where-used list |
+| `abap_object_types` | List searchable object types |
+| `abap_node_contents` | Browse a package's object tree |
+| `abap_transports` | List transport requests |
+
+## Example prompts
+
+- "How does `ZCL_MY_CLASS` work?" — the agent searches, reads the source and
+  related objects.
+- "Find all classes with 'pricing' in the name."
+- "Add method `calculate` to `ZCL_MY_CLASS` and activate it."
+- "Run the unit tests for `ZCL_MY_CLASS` and explain the failures."
+- "Show me the first 20 rows of table `SFLIGHT` where `CARRID = 'LH'`."
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # node --test over tests/**/*.test.ts
+```
+
+The extension is TypeScript loaded directly by pi (via jiti) — no build step.
+
+## Release
+
+Releases use [semantic-release](https://semantic-release.gitbook.io/semantic-release/)
+on the `main` (and `next`) branches. Commits follow Conventional Commits; CI runs the
+test suite, and the release workflow publishes to npm on merge.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,82 @@
+/**
+ * pi ABAP FS Extension
+ *
+ * Provides ABAP remote filesystem capabilities via the ADT (ABAP Development
+ * Tools) protocol, using the `abap-adt-api` package.
+ *
+ * Tools:
+ *   - abap_setup: Configure an SAP connection profile
+ *   - abap_status: Show connection status and profiles
+ *   - abap_profile: List, switch or delete profiles
+ *   - abap_test_connection: Verify a profile can log on
+ *   - abap_search: Search objects by name pattern
+ *   - abap_object_structure: Object metadata and includes
+ *   - abap_read: Read object source code
+ *   - abap_lock / abap_unlock: Lock management
+ *   - abap_write: Write source code (lock + write + unlock)
+ *   - abap_activate: Activate an object
+ *   - abap_syntax_check: Syntax check source
+ *   - abap_unit_test: Run ABAP unit tests
+ *   - abap_query: Run ABAP SQL
+ *   - abap_table: Preview table contents
+ *   - abap_where_used: Where-used list
+ *   - abap_object_types: List searchable object types
+ *   - abap_node_contents: Browse package object tree
+ *   - abap_transports: List user transports
+ *
+ * Data-oriented design:
+ *   - All domain data is represented as plain immutable interfaces (types.ts)
+ *   - I/O is isolated in the client module (client.ts)
+ *   - Pure formatting functions convert data to display strings (formatting/)
+ *   - Each tool is a single-responsibility module (tools/)
+ *   - Configuration is managed as mutable state with file persistence (config.ts)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { loadConfig } from "./src/config.ts";
+import { AbapSetupTool } from "./src/tools/abap-setup.ts";
+import { AbapStatusTool } from "./src/tools/abap-status.ts";
+import { AbapProfileTool } from "./src/tools/abap-profile.ts";
+import { AbapTestConnectionTool } from "./src/tools/abap-test-connection.ts";
+import { AbapSearchTool } from "./src/tools/abap-search.ts";
+import { AbapObjectStructureTool } from "./src/tools/abap-object-structure.ts";
+import { AbapReadTool } from "./src/tools/abap-read.ts";
+import { AbapLockTool } from "./src/tools/abap-lock.ts";
+import { AbapUnlockTool } from "./src/tools/abap-unlock.ts";
+import { AbapWriteTool } from "./src/tools/abap-write.ts";
+import { AbapActivateTool } from "./src/tools/abap-activate.ts";
+import { AbapSyntaxCheckTool } from "./src/tools/abap-syntax-check.ts";
+import { AbapUnitTestTool } from "./src/tools/abap-unit-test.ts";
+import { AbapQueryTool } from "./src/tools/abap-query.ts";
+import { AbapTableTool } from "./src/tools/abap-table.ts";
+import { AbapWhereUsedTool } from "./src/tools/abap-where-used.ts";
+import { AbapObjectTypesTool } from "./src/tools/abap-object-types.ts";
+import { AbapNodeContentsTool } from "./src/tools/abap-node-contents.ts";
+import { AbapTransportsTool } from "./src/tools/abap-transports.ts";
+
+export default function (pi: ExtensionAPI) {
+  // Load saved config on startup.
+  loadConfig();
+
+  // Register all tools.
+  pi.registerTool(AbapSetupTool);
+  pi.registerTool(AbapStatusTool);
+  pi.registerTool(AbapProfileTool);
+  pi.registerTool(AbapTestConnectionTool);
+  pi.registerTool(AbapSearchTool);
+  pi.registerTool(AbapObjectStructureTool);
+  pi.registerTool(AbapReadTool);
+  pi.registerTool(AbapLockTool);
+  pi.registerTool(AbapUnlockTool);
+  pi.registerTool(AbapWriteTool);
+  pi.registerTool(AbapActivateTool);
+  pi.registerTool(AbapSyntaxCheckTool);
+  pi.registerTool(AbapUnitTestTool);
+  pi.registerTool(AbapQueryTool);
+  pi.registerTool(AbapTableTool);
+  pi.registerTool(AbapWhereUsedTool);
+  pi.registerTool(AbapObjectTypesTool);
+  pi.registerTool(AbapNodeContentsTool);
+  pi.registerTool(AbapTransportsTool);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@patimweb/pi-abap-fs",
+  "version": "1.0.0",
+  "description": "ABAP remote filesystem extension for pi coding agent. Read, search, write and activate ABAP objects on SAP systems via the ADT protocol.",
+  "keywords": [
+    "pi-package",
+    "abap",
+    "sap",
+    "adt",
+    "pi-extension"
+  ],
+  "author": "Patrick Weppelmann",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Smotherer007/pi-abap-fs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Smotherer007/pi-abap-fs/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "echo 'No build step defined'",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --experimental-test-module-mocks --test 'tests/**/*.test.ts'",
+    "test:watch": "node --experimental-strip-types --experimental-test-module-mocks --test --watch 'tests/**/*.test.ts'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/Smotherer007/pi-abap-fs/main/screenshot.png"
+  },
+  "dependencies": {
+    "abap-adt-api": "^8.4.3",
+    "typebox": "^1.2.8"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "@semantic-release/git": "^10.0.0",
+    "@types/node": "^24.0.0",
+    "semantic-release": "^25.0.0",
+    "typescript": "^5.8.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,177 @@
+/**
+ * ADT client factory and operation runner.
+ *
+ * Wraps the `abap-adt-api` ADTClient so tools only deal with plain data and
+ * clear, normalized errors. Connection lifecycle is managed per call:
+ * a fresh client is created, logged in, used, and its session dropped.
+ */
+
+import {
+  ADTClient,
+  createSSLConfig,
+  session_types,
+  type AbapObjectStructure,
+  type SearchResult,
+  type ObjectTypeDescriptor,
+} from "abap-adt-api";
+import type { AbapProfile } from "./types.ts";
+import { AbapObjectNotFoundError } from "./types.ts";
+
+// Client creation
+
+export function createClient(
+  profile: AbapProfile,
+  stateful = false,
+): ADTClient {
+  const options = profile.allowUnauthorized ? createSSLConfig(true) : {};
+  const client = new ADTClient(
+    profile.url,
+    profile.username,
+    profile.password,
+    profile.client ?? "",
+    profile.language ?? "",
+    options,
+  );
+  client.stateful = stateful
+    ? session_types.stateful
+    : session_types.stateless;
+  return client;
+}
+
+// Error normalization
+
+function rootMessage(err: unknown): string {
+  const e = err as { message?: string; localizedMessage?: string };
+  if (typeof e?.message === "string" && e.message.length > 0) return e.message;
+  return String(err);
+}
+
+/** Normalize any thrown value into a readable Error for the LLM. */
+export function toError(err: unknown): Error {
+  if (err instanceof Error) {
+    // abap-adt-api errors already carry a useful message; keep it but strip
+    // redundant prefixes so the LLM sees the SAP message directly.
+    return new Error(rootMessage(err));
+  }
+  return new Error(String(err));
+}
+
+// Operation runner
+
+export interface RunOptions {
+  stateful?: boolean;
+}
+
+/**
+ * Run an operation against a freshly-created, logged-in ADT client.
+ * The session is dropped afterwards, and errors are normalized.
+ */
+export async function withClient<T>(
+  profile: AbapProfile,
+  fn: (client: ADTClient) => Promise<T>,
+  options: RunOptions = {},
+): Promise<T> {
+  const client = createClient(profile, options.stateful);
+  try {
+    await client.login();
+    return await fn(client);
+  } catch (err) {
+    throw toError(err);
+  } finally {
+    try {
+      await client.dropSession();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+// Object resolution
+
+export interface ResolvedObject {
+  /** Object name, e.g. ZCL_MY_CLASS */
+  name: string;
+  /** ADT type, e.g. CLAS/OC */
+  type: string;
+  /** Object URL, e.g. /sap/bc/adt/oo/classes/zcl_my_class */
+  objectUrl: string;
+  /** Parsed object structure */
+  structure: AbapObjectStructure;
+  /** Main source include URL (target for getObjectSource / setObjectSource) */
+  mainInclude: string;
+}
+
+/**
+ * Resolve an ABAP object to its structure and main source include.
+ *
+ * Either `objectUrl` (a full ADT object URL) or `name` (with an optional
+ * `type` hint for the search) must be provided.
+ */
+export async function resolveObject(
+  client: ADTClient,
+  params: {
+    name?: string;
+    objectUrl?: string;
+    type?: string;
+  },
+): Promise<ResolvedObject> {
+  let objectUrl: string;
+  let name: string;
+  let type: string;
+
+  if (params.objectUrl) {
+    objectUrl = params.objectUrl;
+    const structure = await client.objectStructure(objectUrl);
+    name = structure.metaData["adtcore:name"] ?? "";
+    type = structure.metaData["adtcore:type"] ?? "";
+    return {
+      name,
+      type,
+      objectUrl,
+      structure,
+      mainInclude: ADTClient.mainInclude(structure),
+    };
+  }
+
+  if (!params.name) {
+    throw new Error("Provide either 'name' or 'objectUrl' to address an object.");
+  }
+
+  const results = await client.searchObject(params.name, params.type, 20);
+  const match = pickSearchResult(results, params.name);
+  if (!match) {
+    throw new AbapObjectNotFoundError(params.name);
+  }
+
+  objectUrl = match["adtcore:uri"];
+  const structure = await client.objectStructure(objectUrl);
+  name = structure.metaData["adtcore:name"] ?? match["adtcore:name"];
+  type = structure.metaData["adtcore:type"] ?? match["adtcore:type"];
+
+  return {
+    name,
+    type,
+    objectUrl,
+    structure,
+    mainInclude: ADTClient.mainInclude(structure),
+  };
+}
+
+/**
+ * Pick the best search result for a query: an exact (case-insensitive) name
+ * match wins, otherwise the first result is used.
+ */
+export function pickSearchResult(
+  results: ReadonlyArray<SearchResult>,
+  query: string,
+): SearchResult | undefined {
+  if (results.length === 0) return undefined;
+  const q = query.toLowerCase();
+  return results.find((r) => r["adtcore:name"].toLowerCase() === q) ?? results[0];
+}
+
+export async function listObjectTypes(
+  client: ADTClient,
+): Promise<ObjectTypeDescriptor[]> {
+  return client.objectTypes();
+}

package/src/config.ts

@@ -0,0 +1,174 @@
+/**
+ * Configuration persistence and state.
+ *
+ * Stores named SAP connection profiles in ~/.pi/abap-config.json.
+ * Supports multiple profiles with an active profile selector.
+ *
+ * File format:
+ *   { "profiles": { "name": AbapProfile, ... }, "activeProfile": "name" }
+ */
+
+import type { AbapProfile, AbapProfiles } from "./types.ts";
+import { AbapNotConfiguredError, AbapProfileNotFoundError } from "./types.ts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// Mutable state
+
+let profiles: Record<string, AbapProfile> = {};
+let activeProfile: string | null = null;
+
+// Path resolution
+
+function configPath(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || "~";
+  return path.join(home, ".pi", "abap-config.json");
+}
+
+// Persistence
+
+/**
+ * Write the profile store.
+ *
+ * The file holds plaintext passwords, so it must never be group- or
+ * world-readable. writeFileSync's `mode` only applies when the file is
+ * created, so an existing file keeps its old (possibly 0644) permissions —
+ * we therefore write to a private temp file and rename it into place. That
+ * is also atomic, so a crash mid-write cannot truncate the config.
+ */
+function persistProfiles(): void {
+  const filePath = configPath();
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+
+  const data: AbapProfiles = { profiles, activeProfile };
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+    fs.chmodSync(tmpPath, 0o600);
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+}
+
+export function loadConfig(): void {
+  try {
+    const filePath = configPath();
+    if (fs.existsSync(filePath)) {
+      const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+
+      // Tighten permissions on config files written by older versions.
+      try {
+        const mode = fs.statSync(filePath).mode & 0o777;
+        if (mode !== 0o600) fs.chmodSync(filePath, 0o600);
+      } catch {
+        /* ignore */
+      }
+
+      if (raw && typeof raw === "object" && raw.profiles) {
+        profiles = raw.profiles;
+        if (raw.activeProfile && profiles[raw.activeProfile]) {
+          activeProfile = raw.activeProfile;
+        } else if (Object.keys(profiles).length > 0) {
+          activeProfile = Object.keys(profiles)[0];
+        } else {
+          activeProfile = null;
+        }
+      }
+    }
+  } catch {
+    profiles = {};
+    activeProfile = null;
+  }
+}
+
+// Access
+
+export function getConfig(): AbapProfile | null {
+  if (!activeProfile) return null;
+  return profiles[activeProfile] ?? null;
+}
+
+export function getConfigOrThrow(): AbapProfile {
+  const config = getConfig();
+  if (!config) {
+    throw new AbapNotConfiguredError();
+  }
+  return config;
+}
+
+/** Get a specific profile by name, or null if not found. */
+export function getProfile(name: string): AbapProfile | null {
+  return profiles[name] ?? null;
+}
+
+/**
+ * Resolve a profile parameter: if a name is given, return that profile
+ * (or throw if not found). Otherwise, return the active profile or throw.
+ */
+export function resolveConfig(profileName?: string): AbapProfile {
+  if (profileName) {
+    const config = getProfile(profileName);
+    if (!config) {
+      throw new AbapProfileNotFoundError(profileName, Object.keys(profiles));
+    }
+    return config;
+  }
+  return getConfigOrThrow();
+}
+
+export function getProfiles(): Record<string, AbapProfile> {
+  return { ...profiles };
+}
+
+export function getActiveProfile(): string | null {
+  return activeProfile;
+}
+
+// Mutations
+
+export function saveProfile(name: string, config: AbapProfile): void {
+  profiles[name] = config;
+  // Auto-set as active if it's the first profile or no active profile.
+  if (!activeProfile || Object.keys(profiles).length === 1) {
+    activeProfile = name;
+  }
+  persistProfiles();
+}
+
+export function setActiveProfile(name: string): void {
+  if (!profiles[name]) {
+    throw new AbapProfileNotFoundError(name, Object.keys(profiles));
+  }
+  activeProfile = name;
+  persistProfiles();
+}
+
+export function deleteProfile(name: string): boolean {
+  if (!profiles[name]) return false;
+  delete profiles[name];
+  if (activeProfile === name) {
+    const keys = Object.keys(profiles);
+    activeProfile = keys.length > 0 ? keys[0] : null;
+  }
+  persistProfiles();
+  return true;
+}
+
+/** @internal Reset state — for testing only */
+export function _resetForTesting(): void {
+  profiles = {};
+  activeProfile = null;
+}