Merge branch 'main' into user-agent

Author: stevensJourney

.github/workflows/onRelease.yml

@@ -16,7 +16,7 @@ jobs:
           cache: 'pnpm'
       - run: pnpm install --frozen-lockfile
       - run: pnpm run build
-      - name: Publish @powersync/cli to npm
-        run: pnpm publish -- --no-git-checks --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      # - name: Publish @powersync/cli to npm
+      #   run: pnpm publish -- --no-git-checks --access public
+      #   env:
+      #     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

AGENTS.md

@@ -11,3 +11,12 @@
 - Prefer mocking env helpers/modules in tests instead of relying on direct `process.env` reads in production code.
 - Tests may set temporary env values when needed, but should primarily validate behavior through mocked env access points.
 - Reset env-related mocks/state between tests to avoid leakage.
+
+## File Naming Conventions
+
+- Choose the filename based on the file's primary responsibility so agents can infer intent without opening the file.
+- If the main export is a class or a type/interface, the filename must exactly match that export name (for example, `ServiceCloudConfig.ts`, `AccountsHubClientSDKClient.ts`).
+- Use this class/type naming rule even if the file also contains small helper functions; the primary exported symbol takes precedence.
+- If the file's purpose is utility logic (single function or a group of helper methods), use action-style kebab-case names in the form `do-this-action.ts` (for example, `ensure-service-type.ts`, `resolve-config-path.ts`).
+- Utility filenames should describe what the code does, not what it is. Prefer verb-led names such as `load-*`, `parse-*`, `validate-*`, `write-*`, `ensure-*`.
+- Avoid generic utility names like `helpers.ts`, `utils.ts`, or `common.ts` unless the file is intentionally a broad shared entry point.

cli/README.md

@@ -42,7 +42,7 @@ npx powersync --version
 The PowerSync CLI lets you manage PowerSync instances and run commands (generate schemas, tokens, validate config, fetch status, and more). Support is split into two modes:
 
 - **Cloud** – Full support for [PowerSync Cloud](https://powersync.com). You can create new instances, deploy and pull config from the Dashboard, and run all Cloud commands. Authenticate with **`powersync login`** (or the `PS_ADMIN_TOKEN` env var), then use **`powersync init cloud`** / **`powersync link cloud`** or **`powersync pull instance`** to work with projects.
-- **Self-hosted** – Limited support for your own PowerSync Service. You link to an existing running instance and can run a subset of commands (e.g. **`powersync fetch status`**, **`powersync generate schema`**, **`powersync validate`**). The CLI does not create, deploy to, or pull config from self-hosted instances; you manage the server and its config yourself. We also expose a [PowerSync Docker topic](../plugins/docker/README.md) for local self-hosted development.
+- **Self-hosted** – Limited support for your own PowerSync Service. You link to an existing running instance and can run a subset of commands (e.g. **`powersync status`**, **`powersync generate schema`**, **`powersync validate`**). The CLI does not create, deploy to, or pull config from self-hosted instances; you manage the server and its config yourself. We also expose a [PowerSync Docker topic](../plugins/docker/README.md) for local self-hosted development.
 
 The sections below go into detail for [Cloud](#cloud) and [Self-hosted](#self-hosted).
 
@@ -126,7 +126,7 @@ To refresh local config after external edits from the cloud when already linked,
 
 ## Running commands against externally managed instances
 
-You can run CLI commands (e.g. **`powersync generate schema`**, **`powersync generate token`**, **`powersync fetch status`**) against a Cloud instance whose configuration is managed elsewhere—for example in the PowerSync Dashboard. No local config directory or link file is required.
+You can run CLI commands (e.g. **`powersync generate schema`**, **`powersync generate token`**, **`powersync status`**) against a Cloud instance whose configuration is managed elsewhere—for example in the PowerSync Dashboard. No local config directory or link file is required.
 
 Specify the instance using **environment variables** or **CLI flags** (flags take precedence): `--instance-id` and `--project-id` (or `INSTANCE_ID`, `PROJECT_ID`). **`--org-id` is optional**: when omitted, the CLI uses the token’s single organization if the token has access to exactly one; if the token has multiple orgs, you must pass **`--org-id`** (or set `ORG_ID`).
 
@@ -143,7 +143,7 @@ powersync generate schema --output-path=schema.ts --output=ts
 
 # Self-hosted
 
-The CLI can run a subset of commands against **self-hosted** PowerSync instances (your own API). Self-hosted support is more limited than Cloud: you link to an existing running API and use the same config directory concept, but only certain commands apply (e.g. **`powersync fetch status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**). There is no **deploy** or **pull instance** for self-hosted; you manage config on the server yourself.
+The CLI can run a subset of commands against **self-hosted** PowerSync instances (your own API). Self-hosted support is more limited than Cloud: you link to an existing running API and use the same config directory concept, but only certain commands apply (e.g. **`powersync status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**). There is no **deploy** or **pull instance** for self-hosted; you manage config on the server yourself.
 
 ## Authentication
 
@@ -169,13 +169,13 @@ The CLI resolves **`!env PS_ADMIN_TOKEN`** from the `PS_ADMIN_TOKEN` environment
 
 ## Creating a self-hosted project and limitations
 
-Run **`powersync init self-hosted`** to scaffold a config directory. Edit **`service.yaml`** with your instance details and use **`!env`** for secrets. This gives you a **partial** project: the CLI does not create or provision a self-hosted instance. You must already have a running PowerSync API. The CLI cannot deploy config to or pull config from a self-hosted instance; you manage **`service.yaml`** and **`sync-config.yaml`** on the server yourself. Use the CLI to link (**`powersync link self-hosted --api-url <url>`**), then run the supported commands (e.g. **`powersync fetch status`**, **`powersync generate schema`**) against that API.
+Run **`powersync init self-hosted`** to scaffold a config directory. Edit **`service.yaml`** with your instance details and use **`!env`** for secrets. This gives you a **partial** project: the CLI does not create or provision a self-hosted instance. You must already have a running PowerSync API. The CLI cannot deploy config to or pull config from a self-hosted instance; you manage **`service.yaml`** and **`sync-config.yaml`** on the server yourself. Use the CLI to link (**`powersync link self-hosted --api-url <url>`**), then run the supported commands (e.g. **`powersync status`**, **`powersync generate schema`**) against that API.
 
 ```sh
 powersync init self-hosted
   # then edit powersync/service.yaml
 powersync link self-hosted --api-url https://powersync.example.com
-powersync fetch status
+powersync status
 ```
 
 Use `--directory` for a different config folder.
@@ -186,7 +186,7 @@ We expose a [PowerSync Docker topic](../plugins/docker/README.md) for running a
 
 ## Command support
 
-Only some CLI commands work with self-hosted instances. Supported commands include **`powersync fetch status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**, and **`powersync link self-hosted`**. Cloud-only commands such as **`powersync deploy`**, **`powersync destroy`**, **`powersync pull instance`**, **`powersync fetch config`**, and **`powersync fetch instances`** do not apply to self-hosted.
+Only some CLI commands work with self-hosted instances. Supported commands include **`powersync status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**, and **`powersync link self-hosted`**. Cloud-only commands such as **`powersync deploy`**, **`powersync destroy`**, **`powersync pull instance`**, **`powersync fetch config`**, and **`powersync fetch instances`** do not apply to self-hosted.
 
 # Known Limitations
 
@@ -245,7 +245,7 @@ You can supply instance and auth context via environment variables (useful for C
 Example (Cloud):
 
 ```sh
-PS_ADMIN_TOKEN=your-token PROJECT_ID=456 INSTANCE_ID=789 powersync fetch status
+PS_ADMIN_TOKEN=your-token PROJECT_ID=456 INSTANCE_ID=789 powersync status
 ```
 
 See [docs/usage.md](../docs/usage.md) for full usage and resolution order (flags, env, cli.yaml).
@@ -560,7 +560,7 @@ DESCRIPTION
 
   Run `docker compose down` then `docker compose up -d --wait`: stops and removes containers, then starts the stack and
   waits for services (including PowerSync) to be healthy. Use when you want a clean bring-up (e.g. after config
-  changes). Use `powersync fetch status` to debug running instances.
+  changes). Use `powersync status` to debug running instances.
 
 EXAMPLES
   $ powersync docker reset
@@ -586,7 +586,7 @@ DESCRIPTION
   Start the self-hosted PowerSync stack via Docker Compose.
 
   Runs `docker compose up -d --wait` for the project docker/ compose file; waits for services (including PowerSync) to
-  be healthy. Use `powersync fetch status` to debug running instances.
+  be healthy. Use `powersync status` to debug running instances.
 
 EXAMPLES
   $ powersync docker start

cli/package.json

@@ -109,7 +109,6 @@
     "build": "tsc -b && pnpm prepack",
     "lint": "eslint",
     "postpack": "shx rm -f oclif.manifest.json",
-    "posttest": "pnpm run lint",
     "pretest": "pnpm run build",
     "readme:generate": "oclif readme && pnpm exec prettier --write README.md",
     "prepack": "oclif manifest && pnpm run readme:generate",

cli/src/commands/deploy/index.ts

@@ -317,7 +317,7 @@ export default class DeployAll extends CloudInstanceCommand {
           sync_rules: project.syncRulesContent ?? ''
         })
         .catch((error) => {
-          if (retry === 9) {
+          if (retry === 99) {
             this.styledError({
               error,
               message: `Failed to validate sync config for instance ${project.linked.instance_id} in project ${project.linked.project_id} in org ${project.linked.org_id}. Ensure the sync config is valid before deploying.`,
@@ -342,6 +342,9 @@ export default class DeployAll extends CloudInstanceCommand {
           suggestions: ['Check your sync config and try again.']
         });
       }
+
+      // Validation succeeded with no errors
+      return;
     }
   }
 
@@ -381,7 +384,7 @@ export default class DeployAll extends CloudInstanceCommand {
       this.log(ux.colorize('green', 'Deployment operation completed successfully!'));
     } else {
       this.styledError({
-        message: `Deploy failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
+        message: `Deploy failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
       });
     }
   }

cli/src/commands/deploy/sync-config.ts

@@ -1,9 +1,10 @@
 import { ux } from '@oclif/core/ux';
 import { routes } from '@powersync/management-types';
 
+import { DEFAULT_DEPLOY_TIMEOUT_MS } from '../../api/cloud/wait-for-operation.js';
 import DeployAll from './index.js';
 
-export class DeploySyncConfig extends DeployAll {
+export default class DeploySyncConfig extends DeployAll {
   static description = 'Deploy only sync config changes.';
   static examples = [
     '<%= config.bin %> <%= command.id %>',
@@ -55,7 +56,7 @@ export class DeploySyncConfig extends DeployAll {
   }
 
   async run(): Promise<void> {
-    const { flags } = await this.parse(DeployAll);
+    const { flags } = await this.parse(DeploySyncConfig);
 
     const project = await this.loadProject(flags, {
       // We don't need the config to be managed locally for this
@@ -65,6 +66,8 @@ export class DeploySyncConfig extends DeployAll {
     const { linked } = project;
     this.parseConfig(project.projectDirectory);
 
+    const deployTimeoutMs = (flags['deploy-timeout'] ?? DEFAULT_DEPLOY_TIMEOUT_MS / 1000) * 1000;
+
     // The existing config is required to deploy changes. The instance should have been created already.
     const cloudConfigState = await this.loadCloudConfigState();
 
@@ -97,7 +100,7 @@ export class DeploySyncConfig extends DeployAll {
         `\nThe instance is not currently provisioned. Triggering a deploy in order to reprovision. This may take a few minutes.\n`
       );
       // Don't yet update the sync config since the instance is not provisioned, but deploy to trigger provisioning
-      await this.deployAll({ cloudConfigState, deployTimeoutMs: flags.timeout, updateSyncConfig: false });
+      await this.deployAll({ cloudConfigState, deployTimeoutMs, updateSyncConfig: false });
     }
 
     // Validate sync config
@@ -106,6 +109,6 @@ export class DeploySyncConfig extends DeployAll {
 
     this.log('Validations completed successfully.\n');
 
-    await this.deploySyncConfig({ cloudConfigState, timeout: flags.timeout });
+    await this.deploySyncConfig({ cloudConfigState, timeout: deployTimeoutMs });
   }
 }

cli/src/commands/destroy.ts

@@ -36,7 +36,7 @@ export default class Destroy extends CloudInstanceCommand {
     spinner.start();
 
     try {
-      const deactivateResult = await client.deactivateInstance({
+      const deactivateResult = await client.destroyInstance({
         app_id: linked.project_id,
         id: linked.instance_id,
         org_id: linked.org_id
@@ -56,7 +56,7 @@ export default class Destroy extends CloudInstanceCommand {
         this.log(ux.colorize('green', 'Instance destroyed successfully.'));
       } else {
         this.styledError({
-          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
+          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
         });
       }
     } catch (error) {

cli/src/commands/link/cloud.ts

@@ -89,15 +89,14 @@ export default class LinkCloud extends CloudInstanceCommand {
         this.styledError({ error, message: 'Failed to create Cloud instance' });
       }
 
-      const projectDir = this.ensureProjectDirectory({ directory });
       ensureServiceTypeMatches({
         command: this,
         configRequired: false,
         directoryLabel: directory,
         expectedType: ServiceType.CLOUD,
-        projectDir
+        projectDir: projectDirectory
       });
-      writeCloudLink(projectDir, { instanceId: newInstanceId, orgId, projectId });
+      writeCloudLink(projectDirectory, { instanceId: newInstanceId, orgId, projectId });
       this.log(
         ux.colorize('green', `Created Cloud instance ${newInstanceId} and updated ${directory}/${CLI_FILENAME}.`)
       );

cli/src/commands/logout.ts

@@ -8,6 +8,7 @@ export default class Logout extends PowerSyncCommand {
   static summary = 'Remove stored auth token.';
 
   async run(): Promise<void> {
+    await this.parse(Logout);
     const { authentication } = Services;
 
     const token = await authentication.getToken();

cli/src/commands/stop.ts

@@ -52,14 +52,13 @@ export default class Stop extends CloudInstanceCommand {
         timeoutMs: 10 * 60 * 1000 // Stopping may take longer than deploying, so use a longer timeout
       });
 
-      // const status = await waitForOperationStatusChange(client, linked, linked.instance_id, stopResult.operation_id, timeoutMs);
       spinner.stop();
 
       if (status === 'completed') {
         this.log(ux.colorize('green', 'Instance stopped successfully.'));
       } else {
         this.styledError({
-          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
+          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
         });
       }
     } catch (error) {