[adm 4] Restore existing/external API connection and automatic data-source discovery

[artiphishle]

Roadmap: #115

Respect the roadmap first and the AGENTS.md file of every repository touched.

Previous roadmap step

[adm 3] (#118) rebuilds minimal instance Properties on top of canonical authoring metadata. This issue restores external/existing API authoring so later binding work can consume real canonical operations/endpoints.

Repository impact

• ankhorage/studio
• ankhorage/data-sources
• ankhorage/contracts only if current canonical data-source contracts genuinely require evolution

Pause at package release boundaries per roadmap rule #6.

Goal

Rebuild the production /ankh/apis flow for connecting existing APIs/services by URL and turning discovered definitions into canonical Ankhorage data sources.

Historical reference

Use ankhorage4 only as behavioral reference, especially the late ApisAdminScreen, ApiCatalogSection, ExternalApiConnectForm, OpenAPI discovery/import flows and earlier GraphQL introspection work.

Important historical nuance: the late discoverExternalApi helper automatically probed OpenAPI locations; GraphQL introspection existed as a separate flow. The new UX may unify discovery ergonomics, but do not falsely model the old helper as already auto-detecting GraphQL.

Requirements

Connect existing API

• user can enter a service/API URL;
• system performs safe discovery of supported descriptions/protocols using current architecture;
• OpenAPI discovery checks appropriate conventional/direct locations;
• OpenAPI documents are parsed/normalized by @ankhorage/data-sources;
• GraphQL introspection uses the canonical GraphQL data-source capability;
• manual REST/OpenAPI/GraphQL authoring/import remains available where still justified;
• no Studio-owned duplicate protocol normalizers.

Data source result

Successful connection creates/updates canonical persisted data-source definitions containing normalized operations/endpoints/schema metadata required by later authoring/runtime flows.

Do not introduce a parallel API catalog model disconnected from manifest/data-source contracts.

Operations and diagnostics

/ankh/apis should provide a production-useful view of connected sources and their operations/endpoints, including appropriate:

• discovery status;
• import/introspection diagnostics;
• endpoint/operation details;
• test/execute capability where supported by canonical data-source tooling;
• clear loading/error/unsupported states.

Do not leak credentials or trusted server-side secrets into browser-readable state.

Likely files

Studio, non-exhaustive:

src/ui/admin/pages/ApisAdminPage.tsx
src/core/StudioProvider.ts
src/manifestState.ts
src/host/http/server.ts
src/host/*

Data-sources, inspect current owners for:

openapi
rest
graphql
test-runner

Do not assume historical filenames are current targets.

Phases

Phase 1 — current contract/discovery audit

Confirm canonical data-source contracts and current @ankhorage/data-sources OpenAPI/REST/GraphQL/test APIs. Make package changes only in the owning repo.

Phase 2 — connection/discovery service

Implement URL-driven discovery/import/introspection through canonical capabilities and persist normalized sources.

Phase 3 — /ankh/apis authoring UX

Build connected-source/operation views, diagnostics and supported testing flows.

Tests

Cover at minimum:

• direct OpenAPI URL discovery;
• conventional OpenAPI endpoint probing;
• valid/invalid OpenAPI import normalization;
• GraphQL introspection request/response integration through canonical helpers;
• manual REST fallback where supported;
• source upsert/persistence;
• duplicate connection behavior;
• diagnostics/error states;
• operation/endpoint listing from normalized source;
• browser-safe responses around credentials.

Acceptance criteria

1. Existing APIs can be connected from /ankh/apis by URL.
2. OpenAPI automatic discovery/import works through @ankhorage/data-sources.
3. GraphQL introspection is restored through its canonical data-source flow.
4. Appropriate manual REST/OpenAPI/GraphQL paths remain available.
5. Connected sources persist canonically.
6. Normalized operations/endpoints are visible and consumable by later binding work.
7. Useful diagnostics/test flows exist where supported.
8. Studio does not duplicate protocol parsing/normalization.
9. No credentials leak into browser-readable state.
10. Behavior-focused tests and full validation pass.
11. No legacy/compatibility/ankhorage4 dependency is introduced.