Merge branch 'stage' into prod

Author: matthew-bernardo

.gitignore

@@ -3,4 +3,5 @@ __pycache__/
 dist/
 cli/.venv/
 cli/build/
-cli/dist/
+cli/dist/
+tests/maxio/

cli/src/stacksync_cli/commands/login.py

@@ -16,11 +16,39 @@
 )
 
 
+def _format_login_status(*, env: dict) -> str:
+    token = env.get("user_api_key")
+    workspaces = env.get("workspaces") or []
+    default_workspace = env.get("default_workspace")
+
+    status = "Logged in" if token else "Not logged in"
+
+    if not token:
+        return status
+
+    if workspaces and not default_workspace:
+        status += " (no default workspace selected, will be prompted on first use of `stacksync create`)"
+    elif not workspaces and not default_workspace:
+        status += " (no workspaces found; no default workspace selected)"
+
+    return status
+
+
 @click.command()
-def login() -> None:
+@click.option(
+    "--check",
+    is_flag=True,
+    help='Print login status ("Logged in" / "Not logged in") and exit.',
+)
+def login(check: bool) -> None:
     """
     The setup command walks the user ID through adding an API key to their account.
     """
+    if check:
+        env = get_env_file()
+        click.echo(_format_login_status(env=env))
+        is_logged_in = bool(env.get("user_api_key"))
+        click.get_current_context().exit(0 if is_logged_in else 1)
     # Step 1: Initialize the `.stacksync` folder in the home directory.
     stacksync_folder = os.path.expanduser("~/.stacksync")
     try:

cli/src/stacksync_cli/main.py

@@ -8,7 +8,50 @@
 from .commands.replay import replay as replay_cmd
 
 
-@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def _help_callback(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
+    if not value or ctx.resilient_parsing:
+        return
+    help_text = """
+    Stacksync CLI
+
+    Usage:
+    $ stacksync <command> [options]
+
+    Commands:
+    $ stacksync login    # Walks the user through adding API credentials to `.stacksync/env.json`
+    $ stacksync create   # Creates a new Stacksync app in the current directory. Generated app includes a reference implementation and a README.md with coding guidelines.
+    $ stacksync dev      # Runs the app locally and enables traffic forwarding from Stacksync Workflows to localhost. Should be run in the repo created by `stacksync create`.
+    $ stacksync replay   # Replays events from the `.logs` folder of the repo to enable iterative debugging and development.
+
+    Development Workflow:
+    Once installed, the Stacksync CLI can be used to create and manage Stacksync Apps.
+    To create an app, the following process is recommended:
+    - Check if logged in: `stacksync login --check`.
+      This will return a status message prefixed with either "Logged in" or "Not logged in".
+    - If not logged in: `stacksync login`
+    - Create an app: `stacksync create <app-name>`
+      This will create a new directory with the specified app-name and populate it with a reference implementation and a README.md with coding guidelines.
+    - Run the app locally before making changes to verify functionality: `stacksync dev`
+    - Once the reference implementation is verified to be working, modify the app as needed, adhering to the coding guidelines in the README.md.
+
+    Debugging:
+    - Event payloads are available for inspection in the `.logs` folder of the repo created by `stacksync create`.
+    - Events can be replayed by index or ID using the `stacksync replay` command.
+    """
+    click.echo(help_text)
+    ctx.exit()
+
+
+@click.group(add_help_option=False)
+@click.option(
+    "-h",
+    "--help",
+    is_flag=True,
+    expose_value=False,
+    is_eager=True,
+    callback=_help_callback,
+    help="Show this message and exit.",
+)
 def cli() -> None:
     pass
 

tests/test_connectors.sh

@@ -0,0 +1,39 @@
+# This test script is designed to check that:
+# 1. The CLI is installable
+# 2. The CLI can be used to create a new connector
+# 3. The connector can be hosted locally
+# It is designed to be run and checked manually by developers.
+
+# 1. The CLI is installable
+curl -fsSL https://cli.stacksync.com/install | sh
+
+# 2. The CLI can be used to create a new connector
+rm -rf maxio
+stacksync create "maxio"
+cd maxio
+
+# 3. The connector can be hosted locally before modifications
+stacksync_dev_cleanup() {
+  if [ -n "${STACKSYNC_DEV_PID:-}" ] && kill -0 "$STACKSYNC_DEV_PID" 2>/dev/null; then
+    kill "$STACKSYNC_DEV_PID" 2>/dev/null || true
+    wait "$STACKSYNC_DEV_PID" 2>/dev/null || true
+  fi
+}
+trap stacksync_dev_cleanup EXIT
+
+stacksync dev &
+STACKSYNC_DEV_PID=$!
+
+sleep 10
+
+# Check that the connector is hosted locally
+curl -fsS http://localhost:2323/health \
+  || { echo "ERROR: GET /health failed" >&2; exit 1; }
+# Check that the connector returns an app config
+curl -fsS http://localhost:2323/app-config \
+  || { echo "ERROR: GET /app-config failed" >&2; exit 1; }
+
+# 4. The connector can be modified using AI using a known good prompt
+prompt="See @README.md and https://developers.maxio.com/http/getting-started/overview. Implement some modules for Maxio."
+# Start the cursor agent and send the prompt
+agent "$prompt"