PSA/ee/docs/plans/alga-cli-and-sdks.md

Alga CLI and SDKs – NPM Publishing Plan

Note on paths: unless stated otherwise, file paths referenced for recent changes are relative to ee/server.

Overview

Goal: Ship an official CLI and SDKs so partners can build and publish Alga client extensions easily. Start with the client SDK and CLI, then add API SDKs. Keep packages modular and composable, with an optional meta entry point.

Package Taxonomy

• @alga-psa/cli: Top-level CLI (bin: alga). Aggregates commands from sub‑SDKs.
• @alga-psa/client-sdk: Programmatic + CLI utilities for client extension development (scaffold, pack, sign, publish).
• @alga-psa/extension-iframe-sdk: Runtime bridge for iframe‑hosted extensions (existing code; ensure final package.json + build).
• @alga-psa/ui-kit: Design tokens + UI primitives for extensions (present; consider renaming scope to @alga-psa/ui-kit).
• @alga-psa/api-sdk (future): HTTP client for Alga APIs.
• @alga-psa/all (optional): Meta package pulling in cli, client-sdk, ui-kit, api-sdk.

Workspace Layout

• Monorepo workspaces: sdk/* (preferred for developer SDKs/CLI) and packages/* (generic libs).
• Recommendation: Place client‑facing developer tooling in sdk/:
  • sdk/alga-client-sdk (programmatic SDK + commands)
  • sdk/alga-cli (thin CLI wrapper delegating to client‑sdk)
  • sdk/extension-iframe-sdk (runtime bridge; move from packages/ for consistency)
  • Keep non‑SDK libraries (e.g., UI tokens) under packages/.

Initial Scope (Phase 1)

1. Scaffold @alga-psa/client-sdk

   • Commands (programmatic + thin CLI wrappers):
     • create extension (scaffold from templates)
     • pack (zip/build artifacts)
     • sign (optional; dev key support)
     • publish (to Alga registry)
   • Templates bundled under templates/* and copied at scaffold time.
   • Expose functions: createNewProject, createUiProject, packProject, sign, publish.

2. Scaffold @alga-psa/cli

   • bin: { "alga": "dist/cli.js" }.
   • Delegates to @alga-psa/client-sdk commands.
   • Commands: alga create extension, alga pack, alga publish, alga sign.

3. Ship @alga-psa/extension-iframe-sdk

   • Ensure package.json, exports, types, and build output.

4. UI Kit

   • If public: rename to @alga-psa/ui-kit. Publish tokens + primitives. Keep CSS tokens accessible via exports.

Conventions

• TypeScript per package: Node 18+, ESM (module: ESNext, moduleResolution: bundler|nodenext).
• Library packages: exports: { ".": "./dist/index.js" }, types: "./dist/index.d.ts", files: ["dist", ...assets].
• CLI package: bin: { "alga": "./dist/cli.js" }, type: "module".
• Scripts: build (tsc), prepublishOnly (build), lint, test.
• Templates: shipped inside client-sdk; avoid network fetch during create.

Release Strategy

• Initial public releases:
  • @alga-psa/client-sdk@0.1.0
  • @alga-psa/cli@0.1.0 (depends on client-sdk)
  • @alga-psa/extension-iframe-sdk@0.x
  • @alga-psa/ui-kit@0.x (public/private per decision)
• Pre‑releases: publish with --tag next while stabilizing.
• Versioning: start manual; adopt Changesets later for coordinated bumps.

Roadmap

• Phase 1 (this PR): client-sdk + CLI, iframe-sdk packaging, optional ui-kit scope alignment.
• Phase 2: API SDK (@alga-psa/api-sdk) with typed clients, auth helpers.
• Phase 3: Meta package @alga-psa/all (optional); improve CLI plugin architecture for additional SDKs.

Next Actions

• Consolidate layout under sdk/ for developer tooling:
  • Move ee/server/packages/alga-client-sdk → sdk/alga-client-sdk (replace older skeleton if needed).
  • Move ee/server/packages/alga-cli → sdk/alga-cli.
  • Move packages/extension-iframe-sdk → sdk/extension-iframe-sdk (or keep in packages/ if we prefer that split).
• Ensure root package.json workspaces include sdk/* (already present) and keep packages/* for generic libs.
• Add build scripts and publishConfig: { access: "public" } where appropriate.
• Normalize scopes (rename @alga/ui-kit → @alga-psa/ui-kit if public).
• Author READMEs with quickstart:
  • npx @alga-psa/cli create extension.
  • Programmatic examples for client-sdk.

Notes

• Keep logic in SDKs; keep CLI thin. This prevents duplication as more SDKs land.
• Bundle only what’s needed in npm (files field) to keep packages lean.