Publish Command

synapse-plugin-helper:publish Command Workflow

Codex Adaptation

• Treat the user request or explicitly supplied text as the command arguments.
• Use the available Codex file, search, terminal, and clarification capabilities that match the workflow.
• Do not depend on Claude-only slash command variables or tool names.

Publish Synapse Plugin

Publish the plugin to the Synapse platform for deployment.

Arguments: the user request or explicit arguments

Pre-Publish Requirements

Prerequisites Check

# Check synapse CLI
synapse --version 2>/dev/null || echo "ERROR: synapse-sdk not installed"

# Check authentication (login required)
synapse doctor 2>/dev/null || echo "WARNING: Not authenticated"

If synapse-sdk not installed:

synapse-sdk가 설치되어 있지 않습니다.
설치: uv pip install synapse-sdk (또는 pip install synapse-sdk)

Checklist

Before publishing, ensure:

1. ✓ config.yaml is complete and valid
2. ✓ All actions are tested with /synapse-plugin:test
3. ✓ Dry run passes with /synapse-plugin:dry-run
4. ✓ Synapse CLI is authenticated (synapse login)

Workflow

Step 1: Pre-Publish Validation

Run a dry-run first:

synapse plugin publish --dry-run

This syncs config from code (synapse plugin update-config equivalent) and previews the upload.

Step 2: Confirm Publishing

Display plugin information and ask for confirmation:

╔══════════════════════════════════════════════════╗
║              PUBLISH CONFIRMATION                ║
╠══════════════════════════════════════════════════╣
║ Plugin: [name]                                   ║
║ Version: [version]                               ║
║ Code: [code]                                     ║
║ Category: [category]                             ║
║                                                  ║
║ Actions to be published:                         ║
║   - train (job)                                  ║
║   - inference (task)                             ║
║   - serve (serve)                                ║
╠══════════════════════════════════════════════════╣
║ Proceed with publishing? [y/N]                   ║
╚══════════════════════════════════════════════════╝

Step 3: Execute Publish

Run the Synapse CLI publish command:

synapse plugin publish

Step 4: Monitor Progress

Display publishing progress:

[1/4] Validating configuration...     ✓
[2/4] Packaging plugin...             ✓
[3/4] Uploading to Synapse...         ✓
[4/4] Registering plugin...           ✓

✓ Plugin published successfully!

Step 5: Post-Publish Information

After successful publishing:

╔══════════════════════════════════════════════════╗
║           PUBLISHING COMPLETE                    ║
╠══════════════════════════════════════════════════╣
║ Plugin ID: [plugin-id]                           ║
║ Version: [version]                               ║
║                                                  ║
║ Your plugin is now available at:                 ║
║ https://synapse.datamaker.kr/plugins/[code]     ║
║                                                  ║
║ Next steps:                                      ║
║ - Test in Synapse UI                             ║
║ - Monitor usage metrics                          ║
║ - Update with 'synapse plugin publish' again     ║
╚══════════════════════════════════════════════════╝

Critical: Publish Scans the Entire Directory Tree

Before uploading, synapse plugin publish runs the same config sync as synapse plugin update-config. That sync calls PluginDiscovery.discover_actions(), which does plugin_dir.rglob('*.py') over the whole project root and imports every BaseAction subclass it finds — then rewrites config.yaml in place ("Synced types from code"). It only skips __pycache__, test_*.py, and conftest.py. It does not honor .synapseignore or .gitignore.

This means any action classes living under the project root get pulled into your config.yaml, overwriting your real entrypoints:

• refs/, examples/, or vendored sample plugins → their train/convert/download/to_task actions get added with foreign entrypoints like refs.yolo.plugin.train.TrainAction.
• A local .venv/ → the SDK's own sample actions get pulled in (e.g. .venv.lib.python3.x.site-packages.synapse_sdk.plugins.testing.sample_actions.*, DefaultExportAction).

The result is a polluted config.yaml and a release that references modules that don't exist at runtime. The archive (.synapseignore) may look clean while the synced config is wrong — check the "Actions:" line in the publish output; if it lists actions you didn't define, the sync was poisoned.

Reliable fix — publish from a clean staging copy via --path so the rglob only sees real plugin files:

rm -rf /tmp/<code>-publish && mkdir -p /tmp/<code>-publish
cp -r plugin config.yaml README.md requirements.txt pyproject.toml .synapseignore /tmp/<code>-publish/
rm -rf /tmp/<code>-publish/plugin/__pycache__
synapse plugin publish --path /tmp/<code>-publish --host <host> --token <token> -y

Moving refs/ out of the tree is not enough on its own when a .venv/ also lives inside the project — the staging copy is the robust approach.

Also exclude large artifacts from the archive. Model checkpoints or zips (e.g. whisper-large-v3.zip, multi-GB weights) left in the project root get archived and uploaded, hanging the publish. Add them to .synapseignore — and note the pattern must match the file: *.zip matches model.zip, but a bare whisper-large-v3 does not match whisper-large-v3.zip.

Options

Error Handling

Authentication required:

✗ Not authenticated with Synapse
  Run: synapse login

Version conflict:

✗ Version 1.0.0 already exists
  Options:
  1. Update version in config.yaml

Network error:

✗ Connection failed
  Check network and retry

Updating Published Plugins

To update an already published plugin:

1. Increment version in config.yaml (or synapse.yaml)
2. Run /synapse-plugin:dry-run to validate
3. Run /synapse-plugin:publish