@invitedlabs/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# invited
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `invited` command connects terminal agents and AI assistants to your Invited Identity. It is a client of Invited's MCP connector (`https://invited.you/mcp`), the same connector Claude and ChatGPT use: it sets up the connector in Claude Code, Cursor, Codex CLI and Gemini CLI, and it can sign in itself to print your public Identity in a terminal.
+
+It reads what your Invited Page already publishes for AI readers and, if you choose to share them, private fragments you pick on Invited's consent screen. It holds an OAuth sign-in like any other connected assistant, never a vault key, and decrypts nothing.
+
+## Install
+
+Node 22.13 or later. Nothing else is installed: the CLI has no dependencies and uses only Node's own modules (`fetch`, `node:crypto`, `node:http`, `node:fs`).
+
+```sh
+npx @invitedlabs/cli connect claude-code   # add Invited to Claude Code, which then signs in itself
+npx @invitedlabs/cli login                 # or sign this CLI in: you approve in your browser
+npx @invitedlabs/cli whoami                # then print your public Identity
+```
+
+or install it once with `npm install --global @invitedlabs/cli` and run `invited …`.
+
+From a checkout of the platform repository, `npm run build:cli` builds `cli/dist` (`npm run build` does it too); then run `node cli/dist/index.js --help`.
+
+## Commands
+
+Every command prints plain English, exits 0 when it did what was asked and 1 otherwise, and uses no colour (set `FORCE_COLOR=1` for bold headings; `NO_COLOR` always wins). `--origin <url>` (or `INVITED_ORIGIN`) points any command at another Invited, such as a local one on `http://127.0.0.1:4180`; the default is `https://invited.you`.
+
+| Command | What it does |
+| --- | --- |
+| `invited connect <host>` | Adds Invited's MCP server to `claude-code`, `cursor`, `codex` or `gemini` as `invited`, keeping every other server in the file as it is. The host then signs in to Invited itself. `--dry-run` prints what it would write and writes nothing; `--bridge` writes the `mcp-remote` bridge instead (`npx -y mcp-remote@0.14.3 https://invited.you/mcp`, pinned to the reviewed version) for a host version without remote sign-in; `--config <file>` edits another file. |
+| `invited login` | Signs this CLI in to your Identity. Your browser opens Invited's consent screen ("Invited CLI wants to understand you"); approve it and the browser returns to the CLI. `--private` also asks for your private fragments: on the same screen you choose the sections and fragments to share and for how long (30 days, 7 days, 24 hours, or until you disconnect). `--no-browser` prints the address to open instead (an SSH session, say). |
+| `invited whoami` | Prints your public Identity as Markdown (`invited://identity`, the same text as your Page's `/identity.md`). `--json` prints `invited://identity.json`. |
+| `invited fragments --type <type>` | Prints your public fragments of one or more types (`get_fragments`); repeat `--type` for more. Types are keys such as `skill`, `language`, `experience`, `cuisines` or `dietaryPreferences`. `--json` prints the structured answer. |
+| `invited fragments --search <words>` | Prints the public fragments that match, best first (`search_fragments`). |
+| `invited private` | Prints the private fragments you share with this CLI (`private_fragments`) and when that sharing ends. `--type <type>` (repeatable) prints only those types; `--json` prints the structured answer. When nothing is shared (you shared none, or the sharing ended) it says so: run `invited login --private` to share again. |
+| `invited status` | Shows the sign-in this CLI holds: your Identity and Page, its scopes (`identity:private` when you shared private fragments with it), when it was last used and when it expires. It reads the credentials file only. |
+| `invited logout` | Revokes this CLI's own sign-in at Invited and deletes its credentials. `invited revoke` does the same. |
+| `invited --help`, `invited help <command>`, `invited --version` | Help and the version. |
+
+Where `connect` writes, and how each host signs in:
+
+| Host | File | Entry | Sign-in |
+| --- | --- | --- | --- |
+| Claude Code | `~/.claude.json` (user scope) | `"invited": { "type": "http", "url": "https://invited.you/mcp" }` | `claude mcp login invited`, or `/mcp` in Claude Code |
+| Cursor | `~/.cursor/mcp.json` | `"invited": { "url": "https://invited.you/mcp" }` | Customize > MCP in Cursor |
+| Codex CLI | `~/.codex/config.toml` (`$CODEX_HOME`) | `[mcp_servers.invited]` `url = "https://invited.you/mcp"` | `codex mcp login invited` |
+| Gemini CLI | `~/.gemini/settings.json` | `"invited": { "httpUrl": "https://invited.you/mcp" }` | when Gemini CLI first connects; `/mcp auth invited` again |
+
+A file the CLI cannot edit safely (JSON with comments, a TOML table written inline) is left as it is, and the CLI prints the entry to add by hand. Running `connect` again changes nothing.
+
+## Your sign-in
+
+`invited login` is OAuth 2.1 with PKCE as the pre-registered public client `invited-cli`. While you approve, the CLI listens on `http://127.0.0.1:<port>/callback`, on a port the system picks, bound to this computer only. The listener accepts one answer, the one carrying this sign-in's `state` and Invited's `iss`, and closes as soon as it arrives, or after 5 minutes.
+
+The sign-in is kept in `~/.invited/credentials.json` (set `INVITED_CONFIG_DIR` to keep it elsewhere): the refresh token, your Identity's id, its scopes, when it was made and last used, and your Page's address. The file is written with mode 0600 in a 0700 folder (on Windows, your user profile's permissions protect it). Access tokens are never written: each command renews one in memory, and Invited issues a new refresh token every time, so the file changes after every command. Two commands at once wait for each other rather than renew the same token.
+
+A sign-in lasts 30 days from its last use, and 90 days at most; then run `invited login` again.
+
+## Reads and the budget
+
+`whoami` and `fragments` are reads of your public Identity, and `private` of what you share privately, the same reads a connected assistant makes. Each one appears in your access log in Settings, under Invited CLI. Invited allows each connection 60 reads a minute; every Invited CLI signed in to your Identity shares one connection, so they share that budget. Past it, the CLI says how many seconds to wait.
+
+## Private fragments
+
+Private fragments reach the CLI only when you share them on the consent screen (`invited login --private`). While they are shared, Invited's server can read those fragments to pass them to the CLI; with your vault on, everything else stays sealed. Settings, Connected assistants shows what is shared and until when, and Disconnect ends it at once.
+
+## Removing it
+
+1. `invited logout` revokes the sign-in and deletes `~/.invited/credentials.json` (the folder `~/.invited` can then go too).
+2. To remove the connection itself, use Settings, Connected assistants: https://invited.you/app/settings. Its reads stay in your access log for 12 months. The CLI can end only its own sign-in; other assistants are disconnected there.
+3. Remove the `invited` entry from each host you connected (`claude mcp remove invited`, or delete it from the file listed above).
+4. `npm uninstall --global @invitedlabs/cli` if you installed it.

package/dist/args.js

@@ -0,0 +1,95 @@
+import { CliError } from './errors.js';
+const VALUES = {
+    '--origin': 'origin',
+    '--config': 'config',
+    '--search': 'search',
+    '--type': 'type',
+};
+const SWITCHES = {
+    '--json': 'json',
+    '--dry-run': 'dryRun',
+    '--bridge': 'bridge',
+    '--no-browser': 'noBrowser',
+    '--private': 'private',
+    '--help': 'help',
+    '-h': 'help',
+    '--version': 'version',
+    '-v': 'version',
+};
+/** Which options each command takes (help and version go with any). */
+export const COMMAND_OPTIONS = {
+    connect: ['--origin', '--dry-run', '--bridge', '--config'],
+    login: ['--origin', '--no-browser', '--private'],
+    whoami: ['--origin', '--json'],
+    fragments: ['--origin', '--json', '--type', '--search'],
+    private: ['--origin', '--json', '--type'],
+    status: ['--origin', '--json'],
+    logout: ['--origin'],
+    revoke: ['--origin'],
+    help: [],
+};
+export function parseArgs(argv) {
+    const flags = {
+        types: [],
+        json: false,
+        dryRun: false,
+        bridge: false,
+        noBrowser: false,
+        private: false,
+        help: false,
+        version: false,
+    };
+    const positionals = [];
+    const given = new Set();
+    let command = null;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!arg.startsWith('-') || arg === '-') {
+            if (command === null)
+                command = arg;
+            else
+                positionals.push(arg);
+            continue;
+        }
+        const equals = arg.startsWith('--') ? arg.indexOf('=') : -1;
+        const name = equals > 0 ? arg.slice(0, equals) : arg;
+        const inline = equals > 0 ? arg.slice(equals + 1) : undefined;
+        if (name in VALUES) {
+            const value = inline ?? argv[++i];
+            if (value === undefined || value === '' || (inline === undefined && value.startsWith('--')))
+                throw new CliError(`${name} needs a value.`);
+            const key = VALUES[name];
+            if (key === 'type')
+                flags.types.push(...value
+                    .split(',')
+                    .map(type => type.trim())
+                    .filter(Boolean));
+            else if (flags[key] !== undefined)
+                throw new CliError(`Give ${name} once.`);
+            else
+                flags[key] = value;
+        }
+        else if (name in SWITCHES) {
+            if (inline !== undefined)
+                throw new CliError(`${name} takes no value.`);
+            flags[SWITCHES[name]] = true;
+        }
+        else
+            throw new CliError(`Unknown option ${name}. Run \`invited --help\` to see the options.`);
+        given.add(name.startsWith('--') ? name : name === '-h' ? '--help' : '--version');
+    }
+    return { command, positionals, flags, given };
+}
+/** Refuse an option the command does not take, so nothing is silently ignored. */
+export function checkOptions(command, given) {
+    const allowed = COMMAND_OPTIONS[command] ?? [];
+    for (const name of given)
+        if (name !== '--help' && name !== '--version' && !allowed.includes(name))
+            throw new CliError(allowed.length
+                ? `\`invited ${command}\` does not take ${name}. It takes: ${allowed.join(', ')}.`
+                : `\`invited ${command}\` takes no options.`);
+}

package/dist/browser.js

@@ -0,0 +1,29 @@
+import { spawn } from 'node:child_process';
+/**
+ * Opens an http(s) address in the person's browser without a shell: the
+ * address is one argument to the system's opener, never parsed by cmd or sh.
+ * Resolves false when the opener cannot start (no desktop, an SSH session);
+ * the address is printed either way.
+ */
+export function openBrowser(url, platform) {
+    if (!/^https?:\/\//.test(url))
+        return Promise.resolve(false);
+    const [command, args] = platform === 'win32'
+        ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    return new Promise(resolve => {
+        try {
+            const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+            child.once('error', () => resolve(false));
+            child.once('spawn', () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/commands.js

@@ -0,0 +1,377 @@
+import { CliError } from './errors.js';
+import { refreshExpiry } from './credentials.js';
+import { duration, formatTime, plural } from './format.js';
+import { listenForCallback } from './loopback.js';
+import { McpError, mcpRequest, ScopeRefused } from './mcp.js';
+import { authorizationUrl, CLIENT_ID, discover, exchangeCode, GrantRefused, newState, pkcePair, PRIVATE_SCOPE, PUBLIC_SCOPE, refreshTokens, revokeRefreshToken, } from './oauth.js';
+export const settingsUrl = (origin) => `${origin}/app/settings`;
+export const settingsLine = (origin) => `Manage every connected assistant in Settings at ${settingsUrl(origin)}.`;
+const iso = (time) => new Date(time).toISOString();
+const notConnected = (origin) => new CliError(`The Invited CLI is not connected to ${origin}. Run \`invited login\` to connect it.`);
+/** Access tokens for this command: one renewal (refresh token rotation)
+ * under the credentials lock, kept in memory only and renewed again when it
+ * nears its hour or the server refuses it. */
+export function accessTokens(ctx, primed) {
+    let current = primed ?? null;
+    return async (force) => {
+        if (current && !force && current.expiresAt - 60_000 > ctx.now())
+            return current.token;
+        current = await ctx.store.locked(async () => {
+            const file = await ctx.store.read();
+            const connection = file.connections[ctx.origin];
+            if (!connection)
+                throw notConnected(ctx.origin);
+            let tokens;
+            try {
+                tokens = await refreshTokens(ctx.fetch, connection, ctx.now());
+            }
+            catch (error) {
+                if (error instanceof GrantRefused)
+                    throw new CliError(`Invited did not renew this CLI's sign-in: ${error.description} Run \`invited login\` to connect again.`);
+                throw error;
+            }
+            file.connections[ctx.origin] = {
+                ...connection,
+                refreshToken: tokens.refreshToken,
+                scopes: tokens.scopes,
+                identityId: tokens.identityId,
+                lastUsedAt: iso(ctx.now()),
+            };
+            await ctx.store.write(file);
+            return { token: tokens.accessToken, expiresAt: tokens.accessExpiresAt };
+        });
+        return current.token;
+    };
+}
+/** Remember the Page a read named, for `invited status`. */
+async function rememberPage(ctx, pageUrl) {
+    if (typeof pageUrl !== 'string' || !/^https?:\/\//.test(pageUrl))
+        return;
+    await ctx.store.locked(async () => {
+        const file = await ctx.store.read();
+        const connection = file.connections[ctx.origin];
+        if (!connection)
+            return;
+        file.connections[ctx.origin] = { ...connection, pageUrl, pageReadAt: iso(ctx.now()) };
+        await ctx.store.write(file);
+    });
+}
+async function readResource(ctx, token, uri) {
+    const result = await mcpRequest(ctx.fetch, ctx.origin, token, 'resources/read', { uri });
+    const content = (Array.isArray(result.contents) ? result.contents[0] : null);
+    if (typeof content?.text !== 'string')
+        throw new CliError('Invited answered without the document.');
+    return { text: content.text, pageUrl: content._meta?.['you.invited/pageUrl'] };
+}
+// login ----------------------------------------------------------------------
+/** The step-up: nothing private is shared with the CLI now. */
+export const NOTHING_SHARED = 'Nothing is shared with the CLI right now. Run `invited login --private` to share fragments.';
+export async function login(ctx, options) {
+    const { noBrowser } = options;
+    const endpoints = await discover(ctx.fetch, ctx.origin);
+    const { verifier, challenge } = pkcePair();
+    const state = newState();
+    const callback = await listenForCallback({
+        state,
+        issuer: endpoints.issuer,
+        requireIss: endpoints.issInResponse,
+        timeoutMs: ctx.loginTimeoutMs,
+    });
+    let tokens;
+    try {
+        const scopes = options.private ? [PUBLIC_SCOPE, PRIVATE_SCOPE] : [PUBLIC_SCOPE];
+        const url = authorizationUrl(endpoints, callback.redirectUri, challenge, state, scopes);
+        ctx.out(options.private
+            ? 'To connect the Invited CLI to your Identity, approve it in your browser and choose the private fragments to share with it.\n'
+            : 'To connect the Invited CLI to your Identity, approve it in your browser.\n');
+        const opened = !noBrowser && (await ctx.openBrowser(url));
+        ctx.out((opened
+            ? 'Your browser should open. If it does not, open this address:\n'
+            : 'Open this address in your browser:\n') +
+            `${url}\nWaiting for your approval (up to ${duration(ctx.loginTimeoutMs)})...\n`);
+        const outcome = await callback.outcome;
+        if (!outcome.ok)
+            throw new CliError(outcome.message);
+        try {
+            tokens = await exchangeCode(ctx.fetch, endpoints, { code: outcome.code, verifier, redirectUri: callback.redirectUri }, ctx.now());
+        }
+        catch (error) {
+            if (error instanceof GrantRefused)
+                throw new CliError(`Invited did not complete the sign-in: ${error.description} Run \`invited login\` again.`);
+            throw error;
+        }
+    }
+    finally {
+        callback.close();
+    }
+    const now = iso(ctx.now());
+    const connection = {
+        origin: ctx.origin,
+        clientId: CLIENT_ID,
+        resource: endpoints.resource,
+        tokenEndpoint: endpoints.token,
+        revocationEndpoint: endpoints.revocation,
+        identityId: tokens.identityId,
+        scopes: tokens.scopes,
+        refreshToken: tokens.refreshToken,
+        connectedAt: now,
+        lastUsedAt: now,
+        pageUrl: null,
+        pageReadAt: null,
+    };
+    const previous = await ctx.store.locked(async () => {
+        const file = await ctx.store.read();
+        const before = file.connections[ctx.origin];
+        file.connections[ctx.origin] = connection;
+        await ctx.store.write(file);
+        return before;
+    });
+    // A sign-in this one replaces ends now rather than in 30 days.
+    if (previous)
+        await revokeRefreshToken(ctx.fetch, previous).catch(() => undefined);
+    // One read names the member's Page; the connection stands either way.
+    let read = 'Connected. The Invited CLI can read your public Identity.';
+    try {
+        const { pageUrl } = await readResource(ctx, accessTokens(ctx, { token: tokens.accessToken, expiresAt: tokens.accessExpiresAt }), 'invited://identity.json');
+        if (typeof pageUrl === 'string') {
+            read = `Connected. The Invited CLI can read the public Identity on ${pageUrl}.`;
+            await rememberPage(ctx, pageUrl);
+        }
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        read = `Connected, but your Page could not be read just now: ${error.message}`;
+    }
+    const shares = tokens.scopes.includes(PRIVATE_SCOPE);
+    ctx.out(`${read}\n` +
+        (shares
+            ? 'It can also read the private fragments you chose to share with it, until that sharing ends.\n'
+            : options.private
+                ? 'You shared no private fragments with it. Run `invited login --private` again to share some.\n'
+                : '') +
+        `Its sign-in is saved in ${ctx.store.path} and lasts 30 days from its last use (90 days at most).\n` +
+        (shares ? 'Try: invited private\n' : 'Try: invited whoami\n'));
+}
+// whoami ---------------------------------------------------------------------
+export async function whoami(ctx, json) {
+    const uri = json ? 'invited://identity.json' : 'invited://identity';
+    let read;
+    try {
+        read = await readResource(ctx, accessTokens(ctx), uri);
+    }
+    catch (error) {
+        if (error instanceof McpError)
+            throw new CliError(error.message);
+        throw error;
+    }
+    ctx.out(read.text.endsWith('\n') ? read.text : read.text + '\n');
+    await rememberPage(ctx, read.pageUrl);
+}
+export async function fragments(ctx, options) {
+    if (options.types.length && options.search !== undefined)
+        throw new CliError('Use --type or --search, not both.');
+    if (!options.types.length && options.search === undefined)
+        throw new CliError('Name a fragment type with --type <type> (repeat it for more), or search with --search <words>. For example: invited fragments --type skill');
+    const call = options.types.length
+        ? { name: 'get_fragments', arguments: { types: [...new Set(options.types)] } }
+        : { name: 'search_fragments', arguments: { query: options.search } };
+    let result;
+    try {
+        result = await mcpRequest(ctx.fetch, ctx.origin, accessTokens(ctx), 'tools/call', call);
+    }
+    catch (error) {
+        if (error instanceof McpError)
+            throw new CliError(error.message);
+        throw error;
+    }
+    const text = Array.isArray(result.content)
+        ? result.content
+            .map(item => (item && typeof item === 'object' && 'text' in item ? String(item.text) : ''))
+            .join('\n')
+        : '';
+    // A tool error is the server's explanation (an unknown type, nothing published).
+    if (result.isError === true)
+        throw new CliError(text || 'Invited could not read those fragments.');
+    let data = result.structuredContent;
+    if (!data) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = undefined;
+        }
+    }
+    if (typeof data?.pageUrl !== 'string' || !Array.isArray(data.fragments))
+        throw new CliError('Invited answered in a form this CLI does not know.');
+    await rememberPage(ctx, data.pageUrl);
+    if (options.json) {
+        ctx.out(JSON.stringify(data, null, 2) + '\n');
+        return;
+    }
+    const list = data.fragments;
+    const what = options.types.length
+        ? `of type ${options.types.join(', ')}`
+        : `matching "${options.search}"${list.length > 1 ? ', best first' : ''}`;
+    if (!list.length) {
+        ctx.out(`No public fragments ${what} on ${data.pageUrl}\n`);
+        return;
+    }
+    const lines = [`${plural(list.length, 'public fragment')} ${what}, from ${data.pageUrl}`, ''];
+    for (const fragment of list) {
+        lines.push(`${ctx.style.bold(fragment.label)}: ${fragment.answer}`);
+        if (fragment.question)
+            lines.push(`  Answers: ${fragment.question}`);
+        lines.push(`  ${fragment.url}`);
+    }
+    ctx.out(lines.join('\n') + '\n');
+}
+/** private_fragments: the private fragments the member shares with the CLI
+ * (step 4b), and when that sharing ends. Nothing shared (none was, it ended,
+ * or the sign-in has only the public scope) is the step-up message. */
+export async function privateFragments(ctx, options) {
+    const types = [...new Set(options.types)];
+    let result;
+    try {
+        result = await mcpRequest(ctx.fetch, ctx.origin, accessTokens(ctx), 'tools/call', {
+            name: 'private_fragments',
+            arguments: types.length ? { types } : {},
+        });
+    }
+    catch (error) {
+        if (error instanceof ScopeRefused && error.scope === PRIVATE_SCOPE)
+            throw new CliError(NOTHING_SHARED);
+        if (error instanceof McpError)
+            throw new CliError(error.message);
+        throw error;
+    }
+    const text = Array.isArray(result.content)
+        ? result.content
+            .map(item => (item && typeof item === 'object' && 'text' in item ? String(item.text) : ''))
+            .join('\n')
+        : '';
+    // A tool error is the server's explanation (an unknown type).
+    if (result.isError === true)
+        throw new CliError(text || 'Invited could not read those fragments.');
+    let data = result.structuredContent;
+    if (!data) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = undefined;
+        }
+    }
+    if (!data || !(data.expiresAt === null || typeof data.expiresAt === 'string') || !Array.isArray(data.fragments))
+        throw new CliError('Invited answered in a form this CLI does not know.');
+    if (options.json) {
+        ctx.out(JSON.stringify(data, null, 2) + '\n');
+        return;
+    }
+    const list = data.fragments;
+    const until = typeof data.expiresAt === 'string'
+        ? `until ${formatTime(data.expiresAt, ctx.timeZone)}`
+        : 'until you disconnect it in Settings or edit the fragment';
+    const what = types.length ? ` of type ${types.join(', ')}` : '';
+    if (!list.length) {
+        ctx.out(`No private fragments${what} are shared with the Invited CLI. Its sharing lasts ${until}.\n`);
+        return;
+    }
+    const lines = [`${plural(list.length, 'private fragment')}${what} shared with the Invited CLI ${until}.`, ''];
+    for (const fragment of list)
+        lines.push(`${ctx.style.bold(fragment.label)}: ${fragment.answer.replace(/\r?\n/g, '\n  ')}`);
+    lines.push('', settingsLine(ctx.origin));
+    ctx.out(lines.join('\n') + '\n');
+}
+// status ---------------------------------------------------------------------
+/** What this CLI holds, from its credentials file alone: no network. Listing
+ * other assistants needs the member's browser session (Settings). */
+export async function status(ctx, json) {
+    const file = await ctx.store.read();
+    const connection = file.connections[ctx.origin];
+    if (!connection) {
+        if (json)
+            ctx.out(JSON.stringify({ connected: false, origin: ctx.origin }, null, 2) + '\n');
+        else
+            ctx.out(`The Invited CLI is not connected to ${ctx.origin}. Run \`invited login\` to connect it.\n`);
+        return 1;
+    }
+    const { expiresAt, latest } = refreshExpiry(connection);
+    const expired = expiresAt <= ctx.now();
+    if (json) {
+        ctx.out(JSON.stringify({
+            connected: !expired,
+            origin: connection.origin,
+            clientId: connection.clientId,
+            identityId: connection.identityId,
+            pageUrl: connection.pageUrl,
+            pageReadAt: connection.pageReadAt,
+            scopes: connection.scopes,
+            connectedAt: connection.connectedAt,
+            lastUsedAt: connection.lastUsedAt,
+            expiresAt: iso(expiresAt),
+            expiresAtLatest: iso(latest),
+            credentialsFile: ctx.store.path,
+            settingsUrl: settingsUrl(ctx.origin),
+        }, null, 2) + '\n');
+        return expired ? 1 : 0;
+    }
+    const time = (value) => formatTime(value, ctx.timeZone);
+    // The public scope first, as every connection holds it.
+    const scopes = [...connection.scopes]
+        .sort((a, b) => Number(b === PUBLIC_SCOPE) - Number(a === PUBLIC_SCOPE))
+        .map(scope => scope === PUBLIC_SCOPE
+        ? 'identity:public (your public Identity)'
+        : scope === PRIVATE_SCOPE
+            ? 'identity:private (the private fragments you share with it)'
+            : scope)
+        .join(', ');
+    const rows = [
+        ['Identity', connection.identityId],
+        [
+            'Page',
+            connection.pageUrl
+                ? `${connection.pageUrl} (as of ${time(connection.pageReadAt ?? connection.lastUsedAt)})`
+                : 'not read yet: run `invited whoami`',
+        ],
+        ['Scopes', scopes],
+        ['Connected', time(connection.connectedAt)],
+        ['Last used', time(connection.lastUsedAt)],
+        [
+            expired ? 'Expired' : 'Expires',
+            expired
+                ? `${time(expiresAt)}: run \`invited login\``
+                : `${time(expiresAt)} unless used before then (${time(latest)} at the latest)`,
+        ],
+        ['Credentials', ctx.store.path],
+    ];
+    ctx.out([
+        ctx.style.bold(`The Invited CLI is signed in to ${connection.origin} (client ${connection.clientId}).`),
+        ...rows.map(([label, value]) => `  ${label.padEnd(13)}${value}`),
+        connection.scopes.includes(PRIVATE_SCOPE)
+            ? 'Run `invited private` to see the private fragments shared with it and when that sharing ends.'
+            : 'It reads no private fragments. Run `invited login --private` to share some with it.',
+        'The CLI can end only its own sign-in (`invited logout`).',
+        settingsLine(ctx.origin),
+    ].join('\n') + '\n');
+    return expired ? 1 : 0;
+}
+// logout ---------------------------------------------------------------------
+export async function logout(ctx, target) {
+    if (target !== undefined && !['invited-cli', 'invited', 'cli'].includes(target))
+        throw new CliError(`The Invited CLI can end only its own sign-in, not ${target}'s. Disconnect ${target} in Settings at ${settingsUrl(ctx.origin)}.`);
+    const ended = await ctx.store.locked(async () => {
+        const file = await ctx.store.read();
+        const connection = file.connections[ctx.origin];
+        if (!connection)
+            return false;
+        await revokeRefreshToken(ctx.fetch, connection);
+        delete file.connections[ctx.origin];
+        await ctx.store.write(file);
+        return true;
+    });
+    ctx.out((ended
+        ? `Revoked the Invited CLI's sign-in to ${ctx.origin} and deleted its credentials from ${ctx.store.path}.\n`
+        : `The Invited CLI was not signed in to ${ctx.origin}; nothing to revoke.\n`) +
+        `Other assistants stay connected. ${settingsLine(ctx.origin)}\n`);
+}