Add declarative integration manifest support

CHANGELOG.md

@@ -6,6 +6,9 @@
  concurrency policy, and system-only consumer Functions in local bundles.
 - Preserve queue-free schema-2 archive compatibility while including declared
  queues in deterministic artifacts and development capability validation.
+- Validate declarative brokered integration slots locally, including
+ project-contained Asana access and app-owned HubSpot CRM capabilities, while
+ keeping integration-free archives byte-compatible with older releases.
 - Add `jobs list|get` for retained production depth, created/retried/succeeded/
  failed rollups, inclusive creation-time filtering, cursor pagination, and
  metadata-only job inspection without payloads or idempotency keys.

src/bundle.test.ts

@@ -158,6 +158,9 @@ functions:
  expect(await readArchivedManifest(root, first.archive)).not.toHaveProperty(
  "queues",
  );
+ expect(await readArchivedManifest(root, first.archive)).not.toHaveProperty(
+ "integrations",
+ );
  });
 
  it("validates and archives declared background queues", async () => {
@@ -200,6 +203,38 @@ queues:
  expect(archived.queues).toEqual(bundle.manifest.queues);
  });
 
+ it("validates and archives declared HubSpot CRM integrations", async () => {
+ const root = await temporaryDirectory();
+ await mkdir(path.join(root, "frontend"));
+ await writeFile(path.join(root, "frontend", "index.html"), "hello");
+ await writeManifest(
+ root,
+ `
+frontend:
+ directory: frontend
+integrations:
+ crm:
+ provider: hubspot-crm
+ account: app
+ cardinality: one
+ capabilities:
+ - crm.contacts.read
+ - crm.contacts.write
+`,
+ );
+
+ const bundle = await buildBundle(root);
+ const archived = await readArchivedManifest(root, bundle.archive);
+
+ expect(bundle.manifest.integrations.crm).toEqual({
+ provider: "hubspot-crm",
+ account: "app",
+ cardinality: "one",
+ capabilities: ["crm.contacts.read", "crm.contacts.write"],
+ });
+ expect(archived.integrations).toEqual(bundle.manifest.integrations);
+ });
+
  it("never archives local .opencloud development metadata", async () => {
  const root = await temporaryDirectory();
  await mkdir(path.join(root, ".opencloud"));

src/index.ts

@@ -21,7 +21,11 @@ import {
  openBrowser,
  revokeAccountCredential,
 } from "./account-auth.js";
-import { buildBundle, OPEN_CLOUD_E2E_TEST_PATH } from "./bundle.js";
+import {
+ buildBundle,
+ OPEN_CLOUD_E2E_TEST_PATH,
+ serializeBundleManifest,
+} from "./bundle.js";
 import { CredentialStore } from "./credential-store.js";
 import { doctorDiagnostics } from "./doctor.js";
 import { devDataRequest, type DevDataAction } from "./dev-data.js";
@@ -115,7 +119,9 @@ function client(): OpenCloudClient {
  const apiUrl = options.apiUrl ?? binding?.apiUrl ?? legacy?.apiUrl;
  if (options.token) {
  if (!apiUrl) {
- throw new Error("Pass --api-url with --token outside a connected workspace.");
+ throw new Error(
+ "Pass --api-url with --token outside a connected workspace.",
+ );
  }
  return new OpenCloudClient({ apiUrl, token: options.token });
  }
@@ -338,7 +344,7 @@ async function synchronizeValidatedDraft(
  for (const file of bundle.files) {
  const content =
  file === "opencloud.json"
- ? Buffer.from(`${JSON.stringify(bundle.manifest, null, 2)}\n`)
+ ? Buffer.from(serializeBundleManifest(bundle.manifest))
  : await readFile(path.join(sourceRoot, ...file.split("/")));
  local.set(file, {
  content,
@@ -547,9 +553,10 @@ program
  process.stderr.write(
  `Open this URL to approve the CLI:\n${authorization.verificationUriComplete}\n`,
  );
- const browserOpened = options.browser !== false
- ? openBrowser(authorization.verificationUriComplete)
- : false;
+ const browserOpened =
+ options.browser !== false
+ ? openBrowser(authorization.verificationUriComplete)
+ : false;
  const account = await completeDeviceAuthorization(authorization);
  const stored = await credentialStore.saveAccount(account);
  output({
@@ -652,16 +659,22 @@ async function logout(): Promise<void> {
  currentWorkspaceCredentialRemoved: Boolean(binding),
  workspaceBindingRetained: binding ? workspaceFile() : null,
  legacyOnboardingSessionRemoved: legacyOnboardingSessionRemoved
- ? legacyOnboardingSession?.state ?? true
+ ? (legacyOnboardingSession?.state ?? true)
  : false,
  next: binding
  ? "The non-secret app binding remains. Run opencloud login to reconnect it later."
  : "Run opencloud login to sign in again.",
  });
 }
 
-auth.command("logout").description("Revoke and clear the CLI login").action(logout);
-program.command("logout").description("Revoke and clear the CLI login").action(logout);
+auth
+ .command("logout")
+ .description("Revoke and clear the CLI login")
+ .action(logout);
+program
+ .command("logout")
+ .description("Revoke and clear the CLI login")
+ .action(logout);
 
 program
  .command("onboard")
@@ -772,7 +785,9 @@ program
 
 program
  .command("doctor")
- .description("Print redacted CLI, identity, endpoint, and platform diagnostics")
+ .description(
+ "Print redacted CLI, identity, endpoint, and platform diagnostics",
+ )
  .action(async () => {
  const options = program.opts<{ apiUrl?: string; token?: string }>();
  const file = sessionFile();
@@ -813,7 +828,7 @@ program
  : stored
  ? "session-file"
  : "none",
- sessionState: binding ? "connected" : stored?.state ?? null,
+ sessionState: binding ? "connected" : (stored?.state ?? null),
  appId:
  binding?.appId ?? (stored?.state === "ready" ? stored.appId : null),
  credentialExpiresAt:
@@ -845,7 +860,9 @@ app
  .option("--idempotency-key <key>")
  .action(async (options) => {
  output(
- await (await managementClient()).call(
+ await (
+ await managementClient()
+ ).call(
  "createApp",
  {
  body: {
@@ -866,17 +883,13 @@ app
 app
  .command("list")
  .description("List apps available to the signed-in account")
- .action(async () =>
- output(await (await managementClient()).get("/v1/apps")),
- );
+ .action(async () => output(await (await managementClient()).get("/v1/apps")));
 
 app
  .command("get")
  .argument("<app-id>")
  .action(async (appId) =>
- output(
- await (await managementClient()).get(`/v1/apps/${appId}`),
- ),
+ output(await (await managementClient()).get(`/v1/apps/${appId}`)),
  );
 
 app
@@ -924,11 +937,7 @@ app
  version?: string;
  sdkVersion?: string;
  };
- if (
- !deployment.id ||
- !deployment.version ||
- !deployment.sdkVersion
- ) {
+ if (!deployment.id || !deployment.version || !deployment.sdkVersion) {
  throw new Error(
  "The active deployment does not expose an OpenCloud SDK pin",
  );
@@ -980,16 +989,18 @@ email
  .option("--limit <number>", "maximum records", "100")
  .option("--alias <alias>", "filter by a manifest-declared alias")
  .addOption(
- new Option("--direction <direction>", "filter by message direction").choices([
- "inbound",
- "outbound",
- ]),
+ new Option(
+ "--direction <direction>",
+ "filter by message direction",
+).choices(["inbound", "outbound"]),
  )
  .option("--from <iso>", "messages created at or after this ISO timestamp")
  .option("--to <iso>", "messages created at or before this ISO timestamp")
  .action(async (appId, options) => {
  output(
- await (await managementClient()).call("getAppEmail", {
+ await (
+ await managementClient()
+ ).call("getAppEmail", {
  appId: String(appId),
  query: emailHistoryQuery(options),
  }),
@@ -1003,7 +1014,9 @@ email
  .argument("<message-id>")
  .action(async (appId, messageId) => {
  output(
- await (await managementClient()).call("getAppEmailMessage", {
+ await (
+ await managementClient()
+ ).call("getAppEmailMessage", {
  appId: String(appId),
  messageId: String(messageId),
  }),
@@ -1141,8 +1154,7 @@ dev
  const state = await requireDevState(callerPath(directory));
  const body = devDataRequest(String(table), action as DevDataAction, {
  id: options.id === undefined ? undefined : String(options.id),
- values:
- options.values === undefined ? undefined : String(options.values),
+ values: options.values === undefined ? undefined : String(options.values),
  });
  output(
  await client().call("mutateDevData", {
@@ -1203,15 +1215,17 @@ devEmail
  new Option("--text <text>", "plain-text body").conflicts("textFile"),
  )
  .addOption(
- new Option("--text-file <path>", "read the plain-text body from a file").conflicts(
- "text",
- ),
+ new Option(
+ "--text-file <path>",
+ "read the plain-text body from a file",
+ ).conflicts("text"),
  )
  .addOption(new Option("--html <html>", "HTML body").conflicts("htmlFile"))
  .addOption(
- new Option("--html-file <path>", "read the HTML body from a file").conflicts(
- "html",
- ),
+ new Option(
+ "--html-file <path>",
+ "read the HTML body from a file",
+ ).conflicts("html"),
  )
  .option("--reply-to <address>", "reserved .test reply-to address")
  .option(
@@ -1300,7 +1314,9 @@ dev
 
 dev
  .command("receipts")
- .description("List exact-revision verification evidence, even after dev stops")
+ .description(
+ "List exact-revision verification evidence, even after dev stops",
+ )
  .argument("[directory]", "app source directory", ".")
  .option("--limit <number>", "maximum records", "50")
  .action(async (directory, options) => {
@@ -1754,7 +1770,7 @@ program
  for (const file of bundle.files) {
  const content =
  file === "opencloud.json"
- ? Buffer.from(`${JSON.stringify(bundle.manifest, null, 2)}\n`)
+ ? Buffer.from(serializeBundleManifest(bundle.manifest))
  : await readFile(path.join(sourceRoot, ...file.split("/")));
  changes.push({
  path: file,
@@ -1997,9 +2013,7 @@ jobs
  .action(async (appId, options) => {
  const query = backgroundJobsQuery(options);
  output(
- await client().get(
- `/v1/apps/${encodeURIComponent(appId)}/jobs?${query}`,
- ),
+ await client().get(`/v1/apps/${encodeURIComponent(appId)}/jobs?${query}`),
  );
  });
 
@@ -2017,9 +2031,7 @@ const secret = program
 
 secret
  .command("rotate")
- .description(
- "Rotate a manifest-generated secret without returning its value",
- )
+ .description("Rotate a manifest-generated secret without returning its value")
  .argument("<app-id>")
  .argument("<name>")
  .option("--bytes <number>", "random byte count", "32")

vendor/bundler/src/index.ts

@@ -47,6 +47,7 @@ interface AuthorManifest {
  email?: unknown;
  health?: unknown;
  secrets?: Record<string, unknown>;
+ integrations?: Record<string, unknown>;
 }
 
 export interface BuiltBundle {
@@ -79,6 +80,19 @@ export interface BundleOptions {
  version?: string;
 }
 
+export function serializeBundleManifest(manifest: OpenCloudManifest): string {
+ const archiveManifest: Partial<OpenCloudManifest> = { ...manifest };
+ // Queue-free schema-2 apps keep the archive shape accepted by older
+ // platform releases while declared queues remain canonical bundle input.
+ if (manifest.queues.length === 0) delete archiveManifest.queues;
+ // Integration-free apps likewise retain the archive shape accepted by
+ // platform releases that predate declarative provider bindings.
+ if (Object.keys(manifest.integrations).length === 0) {
+ delete archiveManifest.integrations;
+ }
+ return `${JSON.stringify(archiveManifest, null, 2)}\n`;
+}
+
 interface BundleSelection {
  files: Map<string, string>;
  directories: Set<string>;
@@ -183,13 +197,9 @@ export async function buildBundle(
  await copyFile(sourceFile, destination);
  await chmod(destination, 0o644);
  }
- const archiveManifest: Partial<OpenCloudManifest> = { ...manifest };
- // Queue-free schema-2 apps keep the archive shape accepted by older
- // platform releases while declared queues remain canonical bundle input.
- if (manifest.queues.length === 0) delete archiveManifest.queues;
  await writeFile(
  path.join(staging, "opencloud.json"),
-`${JSON.stringify(archiveManifest, null, 2)}\n`,
+serializeBundleManifest(manifest),
  { flag: "wx", mode: 0o644 },
  );
 
@@ -227,9 +237,7 @@ export async function buildBundle(
  }
 }
 
-export function assertE2eTestOutsideFrontend(
- frontendDirectory: string,
-): void {
+export function assertE2eTestOutsideFrontend(frontendDirectory: string): void {
  const relative = path.posix.relative(
  frontendDirectory,
  OPEN_CLOUD_E2E_TEST_PATH,