@tomato414941/foundation 0.6.0 → 0.8.0

package/guide.mjs

@@ -104,12 +104,21 @@ export function guide(connectors) {
     '   scopes are the service\'s own names for what the connection may do (see each connector\'s scopes.documentation_url).',
     '   Ask for what the work needs; the owner sees each one before agreeing, and decides. Foundation adds only the few',
     '   it needs to know who authorized (scopes.base). facts.missing_scopes lists any the service did not grant.',
-    '   The owner may connect with an OAuth app of their own instead of Foundation\'s (own_client in GET /v1/connectors):',
-    '   add "client":{"client_id":"<name>","client_secret":"<name>"} naming the given grants that hold its ID and',
-    '   secret (eBay also "ru_name"). Ask for those with a store request first. The app\'s redirect URL is',
-    '   <this server>/oauth/<connector id>/callback. With their own app, the owner also decides which scopes can exist.',
+    '   A connection is made through an OAuth app: Foundation\'s own for the service, or one the owner holds (or was lent).',
+    '   GET /v1/holdings?kind=app   the apps the owner may connect through, Foundation\'s included (foundation: true).',
+    '   Add "app":"<app id>" inside input to connect through one; without it, Foundation\'s is used, or on reconnecting,',
+    '   the app the connection was made through. With their own app the owner decides at the service which scopes can',
+    '   be granted at all, and what name the consent screen shows.',
+    '   POST /v1/requests  {"kind":"app", "input":{"connector":"<id>"}, "purpose":"...", "steps":["..."]}   asks the owner',
+    '     to register one: they make it at the service (redirect URL <this server>/oauth/<connector id>/callback) and',
+    '     type its client ID and secret on the page. result.app_id names it. You never see or handle its secret.',
+    '     GET /v1/connectors says which connectors take apps (apps.fields: what registering one asks for).',
+    '   A service with no connector of its own is reached through "oauth2": the owner registers an app for it naming the',
+    '   service and where it authorizes and hands out tokens (and, if it has them, where it says who authorized and',
+    '   where it takes a token back). Ask for that with {"kind":"app","input":{"connector":"oauth2"}} and steps that say',
+    '   where those are for that service. Connections through it yield OAUTH_ACCESS_TOKEN.',
     '   To reconnect, add "connection_id":"<existing id>" inside input. This updates that connection and keeps its id,',
-    '   its scopes (add more with scopes) and the app it was made with.',
+    '   its scopes (add more with scopes) and the app it was made through.',
     '   Without connection_id, authorization creates a separate connection, even for the same service user. List and use',
     '   an existing connection when no new authorization is needed. Provider consent and revocation may affect several connections.',
     '   A connector whose flow is "role" (aws.role) has the owner make a role for Foundation in their own console and',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomato414941/foundation",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Foundation CLI: make a key, and hand what is kept to a command without it passing through the agent.",
   "type": "module",
   "engines": {

package/runtime.mjs

@@ -109,7 +109,7 @@ Commands:
                                        Run a command with saved values in its environment.
   exec --inputs '<json>' -- <command>  The same, with files, structured inputs, or a connected grant by id.
   exec --output '<json>' -- <command>  Also save a file the command writes.
-  guide                                The API guide: what Foundation keeps, and how to ask it for things.
+  guide                                Read the server's API guide (bundled reference when offline).
   version                              Print the version.
 
 Environment:
@@ -126,15 +126,18 @@ async function main() {
   const configured = process.env.FOUNDATION_URL || await savedUrl();
   if (action === '--help' || action === '-h' || action === 'help' || !action) { console.log(HELP); return; }
   if (action === 'guide') {
-    let connectors;
     if (configured) {
       try {
-        const response = await fetch(new URL('/v1/connectors', configured), { redirect: 'error', signal: AbortSignal.timeout(5_000) });
-        const catalog = await response.json();
-        if (response.ok && Array.isArray(catalog.connectors)) connectors = catalog.connectors;
+        const response = await fetch(new URL('/start', serverUrl(configured)), { redirect: 'error', signal: AbortSignal.timeout(5_000) });
+        if (!response.ok || response.headers.get('content-type')?.split(';')[0].trim() !== 'text/plain') throw new Error('Guide unavailable');
+        const instructions = await response.text();
+        if (!instructions.trim()) throw new Error('Empty guide');
+        console.log(instructions.trimEnd());
+        return;
       } catch {}
     }
-    console.log(guide(connectors));
+    console.error(`${configured ? 'Could not read the server guide.' : 'No Foundation server configured.'} Using the bundled reference from CLI ${VERSION}; it may differ from your server.`);
+    console.log(guide());
     return;
   }
   const separatorAt = args.indexOf('--'), command = separatorAt >= 0 ? args.slice(separatorAt + 1) : [];