284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
81 lines
4.3 KiB
Markdown
81 lines
4.3 KiB
Markdown
# 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.
|