docs: Add comprehensive guide for auto-compilation flow development and deployment strategies #253

jumski · 2025-10-11T17:09:09Z

No description provided.

changeset-bot · 2025-10-11T17:09:12Z

🦋 Changeset detected

Latest commit: ef187d5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
pgflow	Minor
@pgflow/edge-worker	Minor
@pgflow/client	Minor
@pgflow/core	Minor
@pgflow/dsl	Minor
@pgflow/example-flows	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

jumski · 2025-10-11T17:09:24Z

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

merge:queue - adds this PR to the back of the merge queue
hotfix:queue - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

nx-cloud · 2025-10-11T17:10:07Z

View your CI Pipeline Execution ↗ for commit ef187d5

Command	Status	Duration	Result
`nx affected -t verify-exports --base=origin/mai...`	✅ Succeeded	3s	View ↗
`nx affected -t build --configuration=production...`	✅ Succeeded	28s	View ↗
`nx affected -t lint typecheck test --parallel -...`	✅ Succeeded	3m 41s	View ↗
`nx run edge-worker:e2e`	✅ Succeeded	2m 55s	View ↗
`nx run cli:e2e`	✅ Succeeded	6s	View ↗

☁️ Nx Cloud last updated this comment at 2025-11-27 09:38:01 UTC

github-actions · 2025-10-31T09:43:01Z

🔍 Preview Deployment: Playground

✅ Deployment successful!

🔗 Preview URL: https://pr-253--pgflow-demo.netlify.app

📝 Details:

Branch: feat-auto-compilation
Commit: b110c092ab1d460059993a00f02f0c5c66288c7e
View Logs

_Last updated: _

graphite-app · 2025-11-20T17:25:23Z

pkgs/cli/src/commands/compile/index.ts

+      const errorData = await response.json();
+      throw new Error(
+        `Flow '${flowSlug}' not found.\n\n` +
+          `${errorData.message || 'Did you add it to flows.ts?'}\n\n` +
+          `Fix:\n` +
+          `1. Add your flow to supabase/functions/pgflow/flows.ts\n` +
+          `2. Restart edge functions: supabase functions serve`
+      );
+    }


The 404 error handling assumes all 404 responses mean the flow wasn't registered, but the ControlPlane server regex /^/flows/([a-zA-Z0-9_]+)$/ only accepts alphanumeric characters and underscores. If a user passes a slug with hyphens like my-flow, the route won't match and returns a generic 404 with "Route GET /flows/my-flow not found". This code will misleadingly tell users to add the flow to flows.ts when the real issue is invalid characters in the slug.

if (response.status === 404) { const errorData = await response.json(); // Check if it's a route mismatch vs missing flow if (errorData.error === 'Not Found' && errorData.message.includes('Route')) { throw new Error( `Invalid flow slug: '${flowSlug}'\n\n` + `Flow slugs can only contain letters, numbers, and underscores.\n` + `Example: my_flow (not my-flow)` ); } throw new Error( `Flow '${flowSlug}' not found.\n\n` + `${errorData.message || 'Did you add it to flows.ts?'}\n\n` + `Fix:\n` + `1. Add your flow to supabase/functions/pgflow/flows.ts\n` + `2. Restart edge functions: supabase functions serve` ); }

Suggested change

const errorData = await response.json();

throw new Error(

`Flow '${flowSlug}' not found.\n\n` +

`${errorData.message || 'Did you add it to flows.ts?'}\n\n` +

`Fix:\n` +

`1. Add your flow to supabase/functions/pgflow/flows.ts\n` +

`2. Restart edge functions: supabase functions serve`

);

}

const errorData = await response.json();

// Check if it's a route mismatch vs missing flow

if (errorData.error === 'Not Found' && errorData.message.includes('Route')) {

throw new Error(

`Invalid flow slug: '${flowSlug}'\n\n` +

`Flow slugs can only contain letters, numbers, and underscores.\n` +

`Example: my_flow (not my-flow)`

);

}

throw new Error(

`Flow '${flowSlug}' not found.\n\n` +

`${errorData.message || 'Did you add it to flows.ts?'}\n\n` +

`Fix:\n` +

`1. Add your flow to supabase/functions/pgflow/flows.ts\n` +

`2. Restart edge functions: supabase functions serve`

);

}

Spotted by Graphite Agent

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2025-11-21T09:19:59Z

pkgs/cli/scripts/sync-e2e-deps.sh

+find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i 's/\.js"/\.ts"/g' {} +
+find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i "s/\.js'/\.ts'/g" {} +


The sed -i flag behaves differently on macOS vs Linux. On macOS, it requires a backup extension argument (e.g., sed -i ''), while on Linux it doesn't. This will cause the script to fail for developers on macOS.

# Fix for cross-platform compatibility: find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i.bak 's/\.js"/\.ts"/g' {} + && find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.bak" -delete find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i.bak "s/\.js'/\.ts'/g" {} + && find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.bak" -delete

Suggested change

find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i 's/\.js"/\.ts"/g' {} +

find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i "s/\.js'/\.ts'/g" {} +

find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i.bak 's/\.js"/\.ts"/g' {} + && find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.bak" -delete

find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i.bak "s/\.js'/\.ts'/g" {} + && find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.bak" -delete

Spotted by Graphite Agent

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2025-11-25T10:21:32Z

pkgs/cli/src/commands/compile/index.ts

+      '--control-plane-url <url>',
+      'Control plane URL',
+      'http://127.0.0.1:54321/functions/v1/pgflow'
+    )


Port mismatch with CLI package configuration. The default control plane URL uses port 54321, but pkgs/cli/supabase/config.toml configures the API on port 54421 (line 10). This will cause compilation to fail when users run pgflow compile without the --control-plane-url flag in the CLI package's test environment.

.option( '--control-plane-url <url>', 'Control plane URL', 'http://127.0.0.1:54421/functions/v1/pgflow' // Fix: use 54421 )

The E2E test at pkgs/cli/__tests__/e2e/compile.test.ts:139 already works around this by explicitly passing the correct URL, but the default will fail for users.

Suggested change

'--control-plane-url <url>',

'Control plane URL',

'http://127.0.0.1:54321/functions/v1/pgflow'

)

'--control-plane-url <url>',

'Control plane URL',

'http://127.0.0.1:54421/functions/v1/pgflow'

)

Spotted by Graphite Agent

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2025-11-27T05:28:45Z

pkgs/cli/src/commands/compile/index.ts

+      console.error(`[DEBUG] Fetch failed for URL: ${url}`);
+      console.error(`[DEBUG] Error message: ${error.message}`);
+      console.error(`[DEBUG] Error cause:`, (error as any).cause);


Debug logging is unconditionally enabled in production. These console.error statements will always print to stderr when fetch fails, creating noise in production logs.

// Remove debug logging or make it conditional: if (error.message.includes('ECONNREFUSED') || error.message.includes('fetch failed')) { throw new Error( 'Could not connect to ControlPlane.\n\n' + // ... rest of error message ); }

Suggested change

console.error(`[DEBUG] Fetch failed for URL: ${url}`);

console.error(`[DEBUG] Error message: ${error.message}`);

console.error(`[DEBUG] Error cause:`, (error as any).cause);

if (process.env.DEBUG) {

console.error(`[DEBUG] Fetch failed for URL: ${url}`);

console.error(`[DEBUG] Error message: ${error.message}`);

console.error(`[DEBUG] Error cause:`, (error as any).cause);

}

Spotted by Graphite Agent

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2025-11-27T05:28:46Z

pkgs/cli/src/commands/install/create-edge-function.ts

+  }
+
+  if (filesToCreate.some((f) => f.path === denoJsonPath)) {
+    fs.writeFileSync(denoJsonPath, DENO_JSON_TEMPLATE(getVersion()));


If getVersion() returns 'unknown', invalid package specifiers like npm:@pgflow/core@unknown will be written to deno.json, causing import failures when the edge function starts.

if (filesToCreate.some((f) => f.path === denoJsonPath)) { const version = getVersion(); if (version === 'unknown') { throw new Error('Could not determine package version. Check package.json exists.'); } fs.writeFileSync(denoJsonPath, DENO_JSON_TEMPLATE(version)); }

Suggested change

fs.writeFileSync(denoJsonPath, DENO_JSON_TEMPLATE(getVersion()));

const version = getVersion();

if (version === 'unknown') {

throw new Error('Could not determine package version. Check package.json exists.');

}

fs.writeFileSync(denoJsonPath, DENO_JSON_TEMPLATE(version));

Spotted by Graphite Agent

Is this helpful? React 👍 or 👎 to let us know.

…nd deployment strategies

github-actions · 2025-11-27T09:38:45Z

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-253.pgflow.pages.dev

📝 Details:

Branch: feat-auto-compilation
Commit: c66aa1f2f75a53464c285dd730a97960942afc2d
View Logs

_Last updated: _

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

pkgs/edge-worker/src/control-plane/server.ts

graphite-app · 2025-11-28T23:44:59Z

Merge activity

Nov 28, 11:44 PM UTC: jumski added this pull request to the Graphite merge queue.
Nov 28, 11:45 PM UTC: CI is running for this pull request on a draft pull request (#449) due to your merge queue CI optimization settings.
Nov 28, 11:53 PM UTC: Merged by the Graphite merge queue via draft PR: #449.

…nd deployment strategies (#253)

jumski force-pushed the feat-auto-compilation branch from af6bcc5 to d55cc0b Compare October 13, 2025 10:17

jumski temporarily deployed to preview October 13, 2025 10:18 — with GitHub Actions Inactive

jumski force-pushed the feat-auto-compilation branch from d55cc0b to 15033f7 Compare October 31, 2025 09:39

jumski temporarily deployed to preview October 31, 2025 09:40 — with GitHub Actions Inactive

jumski force-pushed the feat-auto-compilation branch from 15033f7 to 6c46ecb Compare November 3, 2025 06:05

jumski temporarily deployed to preview November 3, 2025 06:06 — with GitHub Actions Inactive

jumski force-pushed the feat-auto-compilation branch from 6c46ecb to a25e961 Compare November 5, 2025 18:52

jumski temporarily deployed to preview November 5, 2025 18:54 — with GitHub Actions Inactive

jumski force-pushed the feat-auto-compilation branch from a25e961 to cde9b89 Compare November 17, 2025 06:58

jumski temporarily deployed to preview November 17, 2025 06:59 — with GitHub Actions Inactive

jumski force-pushed the feat-auto-compilation branch from cde9b89 to 56ed82d Compare November 19, 2025 19:58

jumski temporarily deployed to preview November 19, 2025 19:59 — with GitHub Actions Inactive

jumski force-pushed the feat-auto-compilation branch from 56ed82d to dcd753f Compare November 20, 2025 17:21

graphite-app bot reviewed Nov 20, 2025

View reviewed changes

jumski force-pushed the feat-auto-compilation branch from dcd753f to 0d80511 Compare November 21, 2025 09:16

graphite-app bot reviewed Nov 21, 2025

View reviewed changes

jumski force-pushed the feat-auto-compilation branch 6 times, most recently from d55d7e7 to e74ef8e Compare November 25, 2025 10:18

graphite-app bot reviewed Nov 25, 2025

View reviewed changes

jumski force-pushed the feat-auto-compilation branch from e74ef8e to e8886cd Compare November 25, 2025 10:31

jumski force-pushed the feat-auto-compilation branch 5 times, most recently from f95d77b to 1ea4670 Compare November 27, 2025 05:24

graphite-app bot reviewed Nov 27, 2025

View reviewed changes

jumski force-pushed the feat-auto-compilation branch 2 times, most recently from 77bca6f to c4e9c95 Compare November 27, 2025 07:12

jumski temporarily deployed to preview November 27, 2025 07:24 — with GitHub Actions Inactive

jumski force-pushed the feat-auto-compilation branch 2 times, most recently from 251ac47 to b02f41d Compare November 27, 2025 08:34

docs: Add comprehensive guide for auto-compilation flow development a…

ef187d5

…nd deployment strategies

jumski force-pushed the feat-auto-compilation branch from b02f41d to ef187d5 Compare November 27, 2025 09:30

jumski temporarily deployed to preview November 27, 2025 09:37 — with GitHub Actions Inactive

jumski marked this pull request as ready for review November 27, 2025 10:48

jumski mentioned this pull request Nov 27, 2025

chore: remove outdated documentation files and add compile command tests #436

Closed

chatgpt-codex-connector bot reviewed Nov 27, 2025

View reviewed changes

pkgs/edge-worker/src/control-plane/server.ts Show resolved Hide resolved

graphite-app bot pushed a commit that referenced this pull request Nov 28, 2025

docs: Add comprehensive guide for auto-compilation flow development a…

9fa2dd0

…nd deployment strategies (#253)

graphite-app bot closed this Nov 28, 2025

		find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i 's/\.js"/\.ts"/g' {} +
		find "$VENDOR_DIR/@pgflow/edge-worker" -name "*.ts" -type f -exec sed -i "s/\.js'/\.ts'/g" {} +

-    fs.writeFileSync(denoJsonPath, DENO_JSON_TEMPLATE(getVersion()));
+const version = getVersion();
+if (version === 'unknown') {
+    throw new Error('Could not determine package version. Check package.json exists.');
+}
+fs.writeFileSync(denoJsonPath, DENO_JSON_TEMPLATE(version));

docs: Add comprehensive guide for auto-compilation flow development and deployment strategies #253

docs: Add comprehensive guide for auto-compilation flow development and deployment strategies #253

Uh oh!

Conversation

jumski commented Oct 11, 2025

Uh oh!

changeset-bot bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

jumski commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

nx-cloud bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 31, 2025

🔍 Preview Deployment: Playground

Uh oh!

graphite-app bot Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 27, 2025

🔍 Preview Deployment: Website

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

graphite-app bot commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Oct 11, 2025 •

edited

Loading

jumski commented Oct 11, 2025 •

edited

Loading

nx-cloud bot commented Oct 11, 2025 •

edited

Loading

graphite-app bot commented Nov 28, 2025 •

edited

Loading