@trillioncore/cli 1.0.0-next.10 → 1.0.0-next.12

package/README.md

@@ -4,6 +4,20 @@ The `tc` CLI signs you into Trillioncore and reads the organizations and integra
 
 **Requirements:** Node.js 22+, a browser on any device, and a Trillioncore deployment with CLI device login enabled. This is a fresh v1 preview, not v0 command parity; v0 configuration is not imported.
 
+## For agents: install and set up Trillioncore for a person
+
+When a person asks you to install or set up Trillioncore, run these steps in order:
+
+1. Ask whether they already have a Trillioncore account. For a new organization, ask what to call it.
+2. New account: `npm exec --yes --package=@trillioncore/cli@next -- tc signup --organization-name '<name>'`.
+   Existing account, new organization: `... tc create-organization --name '<name>'`.
+   Existing account and organization: `... tc login`.
+3. The command waits up to five minutes for the browser. Run it in the background with output to a file, and add `--no-browser` when the person's browser is on another machine. Read the URL and the separate eight-character code from the output and relay both to the person. They sign up with their provider (for example Google or Microsoft), confirm the organization name, enter the code, and choose access. Wait for the command to print `Signed in`.
+4. Run `tc whoami --json` to confirm the identity.
+5. Relay the printed `Next:` link. The person connects data sources under Integrations in the app. Then use `tc index`, `tc search`, and `tc get`.
+
+Do not ask the person for tokens, passwords, or the verification code in chat. They enter the code only in their browser. Creating an organization makes the person its administrator; it does not approve CLI access by itself.
+
 ## Get started
 
 Once `@next` is published and the hosted login rollout is enabled:
@@ -20,13 +34,15 @@ npm exec --yes --package=@trillioncore/cli@next -- tc logout
 
 `tc login` registers a five-minute request and prints a browser URL plus a separate eight-character code. Open the URL on any device and enter the code shown in your terminal. Keep the code private and approve only a login you started. The CLI polls without a callback listener, tunnel, or copied token. After approval it verifies your identity, saves the private session, and acknowledges delivery.
 
-Browser sign-in lets you choose one or more organizations and explicitly select enabled accounts within each. Membership alone does not authorize a CLI connection; current organization and account permissions still apply. For a brand-new account, finish organization setup and connect your integrations in the app, then rerun `tc login` if prompted. No provider reconnection is required just to authorize the CLI.
+Browser sign-in lets you choose one or more organizations and explicitly select enabled accounts within each. Membership alone does not authorize a CLI connection; current organization and account permissions still apply. For a brand-new account, use `tc signup`; the browser asks for an organization name and continues without a rerun. No provider reconnection is required just to authorize the CLI.
 
 Prefer `npm exec` during evaluation. `npm install -g @trillioncore/cli@next` replaces your local `tc` executable, even though publishing `next` does not change the npm `latest` tag.
 
 ## Commands
 
 - `login [--no-browser] [--api-url <origin>]`: browser authorization, organization/account selection, and durable local session storage.
+- `signup [--organization-name <name>] [--no-browser] [--api-url <origin>]`: create an account on the sign-up screen, name a new organization (you become its administrator), then finish the same device approval as `login`.
+- `create-organization [--name <name>] [--no-browser] [--api-url <origin>]`: an existing account creates another organization in the browser and becomes its administrator. The CLI then signs in through the same device approval, because a new organization needs its own approval. `tc login` also asks a signed-in person with no organization to name one.
 - `whoami [--json]`: verify the signed-in identity without printing credentials.
 - `logout`: revoke the CLI connection on the server and remove its local session. `--local-only` only forgets local credentials; use the app's **Tokens** page to revoke server access if offline.
 - `organizations [--json]`: list only currently approved organizations, with `--limit` and `--cursor` pagination.

package/dist/index.js

@@ -3405,10 +3405,22 @@ function verificationUrl(value, requestId) {
     );
   }
 }
+function organizationSetupUrl(url, options) {
+  if (!options.signUp && !options.createOrganization) return url;
+  const next = new URL(url);
+  if (options.signUp) next.pathname = "/connect/cli/sign-up";
+  else next.searchParams.set("create", "organization");
+  if (options.organizationName)
+    next.searchParams.set("name", options.organizationName);
+  return next.toString();
+}
 async function login(options = {}, environment = process.env) {
   const issuer = loginOrigin(
     options.apiUrl ?? environment.TRILLIONCORE_CLI_API_URL ?? environment.TRILLIONCORE_API_URL ?? DEFAULT_API
   );
+  const organizationName = options.organizationName?.trim();
+  if (organizationName !== void 0 && (!organizationName || organizationName.length > 100 || /[\u0000-\u001f\u007f-\u009f]/.test(organizationName)))
+    throw new Error("Organization name must be 1-100 printable characters.");
   const abort = new AbortController();
   const verifier = randomBytes2(32).toString("base64url");
   const alphabet = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ";
@@ -3475,9 +3487,9 @@ async function login(options = {}, environment = process.env) {
       () => stop("Sign-in timed out. Run tc login again."),
       deadline - Date.now()
     );
-    const authorization = verificationUrl(
-      registration.verification_uri,
-      requestId
+    const authorization = organizationSetupUrl(
+      verificationUrl(registration.verification_uri, requestId),
+      { ...options, ...organizationName ? { organizationName } : {} }
     );
     if (options.onAuthorizationUrl)
       await options.onAuthorizationUrl(authorization, userCode);
@@ -3551,7 +3563,7 @@ Only approve a login you started. Keep the code private.`
           "Signed in, but delivery acknowledgement failed. The temporary delivery expires automatically."
         )
       );
-      return { issuer, ...who };
+      return { issuer, appUrl: new URL(authorization).origin, ...who };
     } catch (error) {
       if (!persisted)
         await revoke(credentials).catch(
@@ -3682,6 +3694,14 @@ var INTEGRATION_PROVIDER_DEFINITIONS = {
     modelVisibility: "declared",
     identity: { source: "externalAccountId", kind: "email", prefix: "", unavailable: "Account email unavailable" }
   },
+  slack: {
+    // Slack workspace identity is retained in the Airbyte binding. The visible local account
+    // identifier is deliberately unique so an organization can keep separate connections.
+    description: "Slack channels and messages",
+    nativeRecordKinds: [],
+    modelVisibility: "declared",
+    identity: { source: "unavailable", unavailable: "Slack workspace identity unavailable" }
+  },
   postgres: {
     // Legacy stored projections remain discoverable; tables use approved manifests.
     description: "PostgreSQL tables",
@@ -3711,7 +3731,7 @@ function integrationProviderDefinition(provider) {
 }
 
 // ../../packages/types/dist/agent.js
-var AGENT_SOURCE_TYPES = ["fathom", "fireflies", "harvest", "outlook", "gmail", "postgres", "github", "google_analytics"];
+var AGENT_SOURCE_TYPES = ["fathom", "fireflies", "harvest", "outlook", "gmail", "slack", "postgres", "github", "google_analytics"];
 var AGENT_SEARCH_FILTER_TYPES = [...AGENT_SOURCE_TYPES, "email"];
 function presentAgentIndex(result, resourceKey) {
   if (resourceKey !== void 0)
@@ -3908,6 +3928,7 @@ function agentHelp(primitive) {
     },
     { name: "create-document", description: "Create a native Markdown/JSON document private to its creator using --organization, --path, --format and --file (UTF8). Requires document read/write opt-in. No integration writes." },
     { name: "update-document", description: "Replace the whole native document text using --ref and --file (UTF8); optional --path/--format/--description. Ref survives path changes. Requires document read/write opt-in." },
+    { name: "act", description: "Perform one provider action on an authorized account, such as sending an email. Syntax: tc act <account-id> <action> --input '<json>' --organization <org-id>. tc index on the account lists its actions and input fields. Requires the connection's actions opt-in (Settings) and the account's admin-granted permission. Actions cannot be undone; confirm with the user before sending to other people." },
     { name: "help", description: "Show supported CLI primitives." }
   ];
   if (!primitive)
@@ -4058,7 +4079,8 @@ async function request(command, path, init, input) {
   }
   if (!response.ok) {
     const authenticationFailure = response.status === 401 || response.status === 403;
-    const envelope = authenticationFailure ? null : parseErrorEnvelope(body);
+    const actionMessage = command === "act" && authenticationFailure ? body?.error?.message : void 0;
+    const envelope = typeof actionMessage === "string" ? agentError("forbidden", actionMessage.slice(0, 300)) : authenticationFailure ? null : parseErrorEnvelope(body);
     throw new CliAgentError(
       envelope ?? agentError(
         authenticationFailure ? "forbidden" : response.status === 404 ? "not_found" : "unavailable",
@@ -4246,6 +4268,22 @@ async function writeDocument(command, input) {
   }, input);
 }
 var createDocument = (input) => writeDocument("create-document", input);
+async function act(input) {
+  let value;
+  try {
+    value = JSON.parse(input.input);
+  } catch {
+    throw new CliAgentError(agentError("invalid_input", "--input must be a JSON object of the action's fields."));
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new CliAgentError(agentError("invalid_input", "--input must be a JSON object of the action's fields."));
+  const config = configuration(input);
+  const parameters = new URLSearchParams();
+  if (!config.pinned && input.organization) parameters.set("organizationId", input.organization);
+  return request("act", config.pinned ? "/api/organizations/:organizationId/agent/act" : `/cli/act?${parameters}`, {
+    method: "POST",
+    body: JSON.stringify({ integrationAccountId: input.accountId, action: input.action, input: value })
+  }, input);
+}
 var updateDocument = (input) => writeDocument("update-document", input);
 function help(primitive) {
   return agentHelp(primitive);
@@ -4320,6 +4358,10 @@ function renderIndex(result) {
           ])
         ];
       }),
+      ...catalog.actions?.length ? [
+        `Actions${catalog.actions.some((action) => !action.available) ? " (turn on actions for this connection in Settings to use)" : ""}: tc act ${accountIdFromPath(catalog.connectionRef) ?? "<account-id>"} <action> --input '<json>'`,
+        ...catalog.actions.flatMap((action) => [`  ${action.name}: ${action.description}`, ...Object.entries(action.input).map(([field, type]) => `    ${field}: ${type}`)])
+      ] : [],
       // The catalog's own details line already names this account; add the generic one only without it.
       ...details.length ? details : ["Details: tc index <account-path> --resource-key <key>"],
       'Search every source at once: tc search "<words>" --grouped',
@@ -4564,6 +4606,7 @@ function createProgram(overrides = {}) {
     createDocument,
     updateDocument,
     agentRequestTraces,
+    act,
     organizations,
     index,
     search,
@@ -4573,17 +4616,19 @@ function createProgram(overrides = {}) {
   };
   const program2 = new Command();
   program2.name("tc").description("Trillioncore CLI \u2014 authorized integration record access").version(CLI_VERSION).helpCommand(false);
-  program2.command("login").description(
-    "Sign in through your browser and choose an organization and accounts"
-  ).option("--api-url <origin>", "Trillioncore API origin").option("--no-browser", "Print the sign-in URL without opening a browser").action(async (options) => {
+  const signIn = async (options, setup = {}) => {
     try {
       const result = await login({
-        apiUrl: options.apiUrl,
-        noBrowser: options.browser === false
+        ...options.apiUrl !== void 0 ? { apiUrl: options.apiUrl } : {},
+        noBrowser: options.browser === false,
+        ...setup,
+        ...options.organizationName !== void 0 ? { organizationName: options.organizationName } : {}
       });
       console.log(
         `Signed in as ${result.email.replace(/[\u0000-\u001f\u007f-\u009f]/g, "")} to ${(result.organizationName ?? "your approved organizations").replace(/[\u0000-\u001f\u007f-\u009f]/g, "")}.`
       );
+      if (setup.signUp || setup.createOrganization)
+        console.log(`Next: connect your data sources under Integrations at ${result.appUrl}`);
       if (process.env.TRILLIONCORE_TOKEN || process.env.TRILLIONCORE_ORG_ID)
         console.error(
           "Manual token/organization environment overrides are set. Unset both to use this browser session."
@@ -4591,7 +4636,16 @@ function createProgram(overrides = {}) {
     } catch (error) {
       writeError(error, false);
     }
-  });
+  };
+  program2.command("login").description(
+    "Sign in through your browser and choose an organization and accounts"
+  ).option("--api-url <origin>", "Trillioncore API origin").option("--no-browser", "Print the sign-in URL without opening a browser").action((options) => signIn(options));
+  program2.command("signup").description(
+    "Create a Trillioncore account and organization in your browser, then sign in this CLI"
+  ).option("--api-url <origin>", "Trillioncore API origin").option("--no-browser", "Print the sign-up URL without opening a browser").option("--organization-name <name>", "Suggested organization name; the browser asks to confirm it").action((options) => signIn(options, { signUp: true }));
+  program2.command("create-organization").description(
+    "Create another organization in your browser; you become its administrator and this CLI signs in to it"
+  ).option("--name <name>", "Suggested organization name; the browser asks to confirm it").option("--api-url <origin>", "Trillioncore API origin").option("--no-browser", "Print the URL without opening a browser").action((options) => signIn({ ...options, organizationName: options.name }, { createOrganization: true }));
   program2.command("whoami").description("Verify your current CLI identity").option("-j, --json", "Output identity without credentials").action(async (options) => {
     try {
       const result = await whoami();
@@ -4696,6 +4750,14 @@ ${AGENT_DISCOVERY_GUIDANCE}`).option("--organization <id>", "Target an approved
       }
     });
   }
+  program2.command("act <account-id> <action>").description("Perform one provider action, such as gmail.send_email; tc index on the account lists its actions. Requires the connection's actions opt-in. Actions cannot be undone.").requiredOption("--input <json>", "JSON object of the action's input fields").option("--organization <id>", "Explicit approved organization; must match any configured pin").option("-j, --json", "Output shared DTO JSON").action(async (accountId, action, options) => {
+    try {
+      const result = await commands.act({ accountId, action, input: options.input, ...options.organization ? { organization: options.organization } : {} });
+      writeResult(result, Boolean(options.json), JSON.stringify(result, null, 2));
+    } catch (error) {
+      writeError(error, Boolean(options.json));
+    }
+  });
   program2.command("help [primitive]").description("Show supported CLI primitives").option("-j, --json", "Output shared DTO JSON").action((primitive, options) => {
     const result = commands.help(primitive);
     if (isAgentError(result)) {
@@ -4710,7 +4772,7 @@ if (process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === realpathSyn
   try {
     const program2 = createProgram();
     program2.hook("preAction", async (_program, command) => {
-      if (!["organizations", "index", "search", "get", "sql", "create-document", "update-document", "agent-request-traces"].includes(command.name())) return;
+      if (!["organizations", "index", "search", "get", "sql", "create-document", "update-document", "act", "agent-request-traces"].includes(command.name())) return;
       const effective = await authenticatedEnvironment();
       for (const key of [
         "TRILLIONCORE_CLI_API_URL",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillioncore/cli",
-  "version": "1.0.0-next.10",
+  "version": "1.0.0-next.12",
   "description": "Trillioncore v1 CLI: sign in and read your authorized integration records",
   "type": "module",
   "license": "MIT",