@salsita-ai/sdk 0.50.0-develop.9ed52379e9 → 0.50.0-develop.a4dde5f252
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/dist/application-spec/generate-application/code/templates/package-json.js +1 -1
- package/dist/docs/index.json +1 -1
- package/dist/docs/integrations/woocommerce/local-development.mdx +1 -1
- package/dist/docs/phoenix/phoenix-cli.mdx +16 -25
- package/dist/docs/phoenix/project-structure.mdx +1 -1
- package/dist/docs/phoenix/quickstart.mdx +2 -2
- package/dist/docs/phoenix/sdk-builder-workflow.mdx +2 -2
- package/dist/docs/phoenix/webhooks.mdx +1 -1
- package/dist/phoenix/commands/init.d.ts +4 -4
- package/dist/phoenix/commands/init.js +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -44,8 +44,8 @@ Run the CLI through the project's package manager so its version matches the ins
|
|
|
44
44
|
|
|
45
45
|
| Command | What it does |
|
|
46
46
|
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
|
47
|
-
| `phoenix init [folder]` | Starts a project: `package.json` when missing, and a starter spec.
|
|
48
|
-
| `phoenix sync` | Regenerates project files and aligns dependencies
|
|
47
|
+
| `phoenix init [folder]` | Starts a project: `package.json` when missing, the five project scripts it lacks, and a starter spec. |
|
|
48
|
+
| `phoenix sync` | Regenerates project files and aligns dependencies. |
|
|
49
49
|
| `phoenix dev` | Development server with hot reload, webhook tunnel and the editor. |
|
|
50
50
|
| `phoenix build` | Production build of the frontend and the webhooks. |
|
|
51
51
|
| `phoenix check` / `fix` | Type check, lint and format; `fix` applies the automatic fixes. |
|
|
@@ -1 +1 @@
|
|
|
1
|
-
let e=["@salsita-ai/platform-project-sdk","@salsita-ai/platform-common","@salsita-ai/platform-contracts","@salsita-ai/common","@salsita-ai/contracts"],t=
|
|
1
|
+
let e=["@salsita-ai/platform-project-sdk","@salsita-ai/platform-common","@salsita-ai/platform-contracts","@salsita-ai/common","@salsita-ai/contracts"],t={private:!0,type:"module",packageManager:"pnpm@11.1.3",engines:{node:"24.14.1",pnpm:"11.1.3"}},r={"babel-plugin-macros":"3.1.0",vite:"6.4.3","@vitejs/plugin-react":"5.2.0","@swc/cli":"0.8.1","@swc/core":"1.15.40",typescript:"npm:@typescript/typescript6@6.0.2","@lingui/cli":"5.9.5","@types/lodash-es":"4.17.12","@lingui/macro":"5.9.5","@lingui/swc-plugin":"5.11.0","@types/node":"24.12.2","@types/react":"18.3.8","@types/react-dom":"18.3.0","@types/three":"0.160.0","@typescript/native":"npm:typescript@7.0.2",envalid:"8.1.1",eslint:"9.39.4",prettier:"3.8.3",vitest:"4.1.11"},i=e=>"object"==typeof e&&null!==e&&!Array.isArray(e),a=e=>{if(!i(e))return;let t=[];for(let[r,i]of Object.entries(e)){if("string"!=typeof i)return;t.push([r,i])}return Object.fromEntries(t)},s=e=>e.replace(/^[\^~]/,""),n=(t,r)=>{let i={};for(let[e,r]of Object.entries(t))i[e]=s(r);if(r)for(let[e,t]of Object.entries(r))e in i||(i[e]=s(t));return Object.fromEntries(Object.entries(i).filter(([t])=>!e.includes(t)).sort(([e],[t])=>e>t?1:e<t?-1:0))};export const generateApplicationSpecPackageJson=e=>{let{sdkVersion:s,useWorkspace:c,useClerk:o=!1,name:p,description:l,existingContent:m}=e,u=(e=>{if(!e)return{};try{let t=JSON.parse(e);if(i(t))return t}catch{}return{}})(m),f=n({...o?{"@clerk/clerk-react":"5.61.8"}:{},"camera-controls":"2.4.2","lodash-es":"4.18.1",react:"18.3.1","react-dom":"18.3.1","@emotion/react":"11.11.3","@emotion/styled":"11.11.0","@mui/material":"5.15.5","@mui/system":"5.16.7","@lingui/core":"5.9.5","@lingui/react":"5.9.5",three:"0.160.1","@react-three/fiber":"8.15.16","@react-three/drei":"9.97.6","@react-three/postprocessing":"2.16.3",motion:"12.34.0","@tanstack/react-query":"5.100.14",rxjs:"7.8.2",uuid:"14.0.0","ts-pattern":"5.9.0","@salsita-ai/sdk":c?"workspace:^":s,zod:"3.25.76"},a(u.dependencies)),d=n(r,a(u.devDependencies)),y=u.name,g=p?p.toLowerCase().replace(/[^a-z0-9-]/g,"-"):"string"==typeof y?y:"project-name",j={...u,name:g,...t,dependencies:f,devDependencies:d};return void 0!==l&&(j.description=l),JSON.stringify(j,null,2)+"\n"};
|
package/dist/docs/index.json
CHANGED
|
@@ -133,7 +133,7 @@ The value of `WOOCOMMERCE_API_KEY` must correspond to the value of the 'API key'
|
|
|
133
133
|
settings page and `WOOCOMMERCE_PRODUCT_NAME` must correspond to the name of the product template you created.
|
|
134
134
|
|
|
135
135
|
- run development server (from this repo): `pnpm dev:server`
|
|
136
|
-
- prepare local deployment (from the implementation project): `pnpm deployment:prepare-local`
|
|
136
|
+
- prepare local deployment (from the implementation project): `pnpm phoenix deployment:prepare-local`
|
|
137
137
|
- start the dev process (from the implementation project): `pnpm dev`
|
|
138
138
|
- run bundle build (from the implementation project): `pnpm build`
|
|
139
139
|
|
|
@@ -29,8 +29,9 @@ pnpm phoenix dev
|
|
|
29
29
|
|
|
30
30
|
1. Refuses to run when a `spec/` folder already exists, so it never touches an existing project.
|
|
31
31
|
2. Writes a `package.json` that depends on the CLI's SDK version when the folder has none. An existing `package.json` is kept, as long as it depends on the SDK.
|
|
32
|
-
3.
|
|
33
|
-
4. Writes `
|
|
32
|
+
3. Adds the `dev`, `build`, `deploy`, `check` and `fix` scripts to `package.json` (see [Project Scripts](#project-scripts)). A script the project already has under one of those names keeps its command.
|
|
33
|
+
4. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
|
|
34
|
+
5. Writes `pnpm-workspace.yaml` with the pnpm settings the first install needs: the build scripts of the SDK's dependencies are allowed or denied, and `@salsita-ai/*` packages are exempt from pnpm's minimum release age. A project inside a pnpm monorepo gets no file; the workspace root holds these settings.
|
|
34
35
|
|
|
35
36
|
It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs).
|
|
36
37
|
|
|
@@ -114,8 +115,6 @@ For quick local development without a server, use:
|
|
|
114
115
|
|
|
115
116
|
```bash
|
|
116
117
|
phoenix dev --persistence local-storage
|
|
117
|
-
# or use the shortcut script:
|
|
118
|
-
pnpm dev:local
|
|
119
118
|
```
|
|
120
119
|
|
|
121
120
|
**Important:** The server must be running before `deployment:prepare-local` when using `server` persistence mode.
|
|
@@ -158,27 +157,19 @@ spec/application.yaml → Server prepares environment → CLI writes .env.genera
|
|
|
158
157
|
|
|
159
158
|
### Project Scripts
|
|
160
159
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
| Script
|
|
164
|
-
|
|
|
165
|
-
| `dev`
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
| `prettify:fix` | `prettier --write .` | Prettier fix only |
|
|
175
|
-
| `verify:fix` | `phoenix build && phoenix fix && phoenix check --types` | Build, fix, then type-check |
|
|
176
|
-
| `test` | `vitest --passWithNoTests run` | Run tests |
|
|
177
|
-
| `test:watch` | `vitest` | Tests in watch mode |
|
|
178
|
-
| `prepare:ci` | `phoenix prepare:ci` | CI environment setup |
|
|
179
|
-
| `deployment:prepare-local` | `phoenix deployment:prepare-local` | Prepare local environment |
|
|
180
|
-
|
|
181
|
-
Custom scripts you add to `package.json` are preserved during sync. Deprecated scripts (like `environment:create`, `deployment:register`) are automatically removed.
|
|
160
|
+
`phoenix init` writes five scripts into `package.json`, each a shortcut for the CLI command of the same name:
|
|
161
|
+
|
|
162
|
+
| Script | Command | Purpose |
|
|
163
|
+
| -------- | ---------------- | --------------------------------------------- |
|
|
164
|
+
| `dev` | `phoenix dev` | Dev server with hot reload |
|
|
165
|
+
| `build` | `phoenix build` | Production build |
|
|
166
|
+
| `deploy` | `phoenix deploy` | Build and publish the project |
|
|
167
|
+
| `check` | `phoenix check` | Run all checks (TypeScript, ESLint, Prettier) |
|
|
168
|
+
| `fix` | `phoenix fix` | Auto-fix lint and formatting issues |
|
|
169
|
+
|
|
170
|
+
The scripts are yours: change, rename or delete them, and add your own. `phoenix sync` and `phoenix clean` leave the `scripts` section of `package.json` as it is, so they add no script, restore none you removed and remove none. Every CLI command also runs without a script, as `pnpm phoenix <command>`.
|
|
171
|
+
|
|
172
|
+
A project may have other scripts than these five, such as `sync`, `test` or `verify:fix`; they are its own and stay as they are. All of this holds for a project on the application-spec pipeline, which `phoenix init` selects. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix sync` and `phoenix clean` write their own set of scripts into `package.json` on every run, over scripts of the same name.
|
|
182
173
|
|
|
183
174
|
### Server-Generated Variables
|
|
184
175
|
|
|
@@ -178,7 +178,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
|
|
|
178
178
|
|
|
179
179
|
| File | Auto-Generated? | Notes |
|
|
180
180
|
| ------------------------------------------------------ | --------------- | -------------------------------------- |
|
|
181
|
-
| `package.json` | Partially | Dependencies merged, scripts
|
|
181
|
+
| `package.json` | Partially | Dependencies merged, scripts untouched |
|
|
182
182
|
| `tsconfig.json` | Yes | Managed by Phoenix |
|
|
183
183
|
| `eslint.config.js` | Yes | Managed by Phoenix |
|
|
184
184
|
| `prettier.config.js` | Yes | Managed by Phoenix |
|
|
@@ -104,10 +104,10 @@ pnpm install
|
|
|
104
104
|
pnpm phoenix sync
|
|
105
105
|
```
|
|
106
106
|
|
|
107
|
-
`phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell,
|
|
107
|
+
`phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, types, and `.phoenix/` implementation. Start development without a server:
|
|
108
108
|
|
|
109
109
|
```sh
|
|
110
|
-
pnpm dev
|
|
110
|
+
pnpm phoenix dev --persistence local-storage
|
|
111
111
|
```
|
|
112
112
|
|
|
113
113
|
Open the URL printed by the command. The application shell loads with the default `<salsita-configurator>` element and an empty 3D scene.
|
|
@@ -22,7 +22,7 @@ pnpm install
|
|
|
22
22
|
pnpm phoenix sync
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it. `phoenix sync` then adds the rest of the project:
|
|
25
|
+
`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it, and its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: webhooks and lint config.
|
|
26
26
|
|
|
27
27
|
`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK.
|
|
28
28
|
|
|
@@ -61,7 +61,7 @@ Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it s
|
|
|
61
61
|
|
|
62
62
|
Every user who signs the CLI in gets their own development environment, so a teammate (a super admin of the workspace, like you) who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
|
|
63
63
|
|
|
64
|
-
`pnpm dev
|
|
64
|
+
`pnpm phoenix dev --persistence local-storage` still runs the project without any server, with state kept in the browser.
|
|
65
65
|
|
|
66
66
|
Coding agents follow the generated `phoenix` skill: before their first change they start `phoenix dev` and open the preview in your browser, and after `phoenix deploy` starts a build they open its page in Studio.
|
|
67
67
|
|
|
@@ -991,7 +991,7 @@ Save the same OAuth client ID, client secret, and base URL in the customer's **C
|
|
|
991
991
|
JWT_SECRET_BASE64=<base64 of a long random key>
|
|
992
992
|
```
|
|
993
993
|
|
|
994
|
-
For a deployment, run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, run `pnpm deployment:prepare-local`. These current commands use the customer settings stored in Studio; the removed `environment:create` and `deployment:register` commands are not part of the setup flow.
|
|
994
|
+
For a deployment, run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, run `pnpm phoenix deployment:prepare-local`. These current commands use the customer settings stored in Studio; the removed `environment:create` and `deployment:register` commands are not part of the setup flow.
|
|
995
995
|
|
|
996
996
|
#### Clerk organization
|
|
997
997
|
|
|
@@ -6,10 +6,10 @@ export interface InitCommandProps {
|
|
|
6
6
|
}
|
|
7
7
|
/**
|
|
8
8
|
* Starts a Phoenix project: writes a `package.json` that depends on this CLI's SDK version when the folder has none,
|
|
9
|
-
* the starter spec and the pnpm settings the first install needs,
|
|
10
|
-
* pipeline. It touches no
|
|
11
|
-
* nothing: the starter spec names the default project of whichever workspace the developer signs in
|
|
12
|
-
* everything else is generated by sync or the build.
|
|
9
|
+
* the starter spec and the pnpm settings the first install needs, adds the `dev`, `build`, `deploy`, `check` and `fix`
|
|
10
|
+
* scripts the project does not have yet, and switches the project to the application-spec pipeline. It touches no
|
|
11
|
+
* server and asks nothing: the starter spec names the default project of whichever workspace the developer signs in
|
|
12
|
+
* to, and everything else is generated by sync or the build.
|
|
13
13
|
*
|
|
14
14
|
* Refuses when a `spec/` folder exists, and when an existing `package.json` does not depend on the SDK.
|
|
15
15
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{existsSync as e}from"fs";import{mkdir as n,readFile as t,writeFile as i}from"fs/promises";import{basename as o,dirname as r,join as p}from"path";import{ensureWorkspaceInstallSettings as
|
|
1
|
+
import{existsSync as e}from"fs";import{mkdir as n,readFile as t,writeFile as i}from"fs/promises";import{basename as o,dirname as r,join as p}from"path";import{ensureWorkspaceInstallSettings as s}from"../utils/index.js";import{starterSpecFiles as a}from"./init-starter-spec.js";let c="@salsita-ai/sdk",l={dev:"phoenix dev",build:"phoenix build",deploy:"phoenix deploy",check:"phoenix check",fix:"phoenix fix"},d=async e=>{let n=`Install the SDK first (\`pnpm add ${c}\`), then rerun \`pnpm phoenix init\`.`,i=JSON.parse(await t(e,"utf-8"));if("object"!=typeof i||null===i||Array.isArray(i))throw Error(`phoenix init could not read package.json because it is not a JSON object. ${n}`);if(!["dependencies","devDependencies"].some(e=>{let n=Reflect.get(i,e);return"object"==typeof n&&null!==n&&c in n}))throw Error(`phoenix init found no ${c} dependency in package.json. ${n}`);return{...i}},h=async e=>{for(let t of a){let o=p(e,t.path);await n(r(o),{recursive:!0}),await i(o,t.content)}},f=async(e,n)=>{let t=n.phoenix,o=n.scripts,r="object"==typeof o&&null!==o?o:{},p=Object.fromEntries(Object.entries(l).filter(([e])=>!(e in r)));await i(e,JSON.stringify({...n,scripts:{...r,...p},phoenix:{..."object"==typeof t&&null!==t?t:{},applicationFlow:!0}},null,2)+"\n")};export const runInitCommand=async(t,{logger:i})=>{var r,a;let u,m=t.projectRoot??process.cwd(),x=p(m,"package.json");if(e(p(m,"spec")))throw Error("phoenix init found an existing spec/ folder. init only starts new projects, and writing a starter spec would overwrite or mix with the existing one. To update an existing project, run `pnpm phoenix sync`; to start over, run init in an empty project folder.");let w=e(x)?await d(x):(r=m,a=t.sdkVersion,{name:(u=o(r).toLowerCase().replace(/[^a-z0-9._-]+/g,"-").replace(/^[._-]+|[-]+$/g,"")).length>0?u:"phoenix-configurator",private:!0,type:"module",scripts:l,dependencies:{[c]:a},devDependencies:{"@lingui/cli":"5.9.5","@lingui/swc-plugin":"5.11.0"}});i.step(`Writing the starter project to ${m}`),await n(m,{recursive:!0}),await h(m),await f(x,w),s(m),i.success(`Phoenix project created in ${m}.`),i.info("\nNext steps, in the project folder:\n pnpm install\n pnpm phoenix sync\n pnpm phoenix login <workspace>\n pnpm phoenix dev\n pnpm phoenix deploy\n\nDeveloping against a Studio development environment instead? Paste its .env block into .env before phoenix dev.")};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@salsita-ai/sdk",
|
|
3
|
-
"version": "0.50.0-develop.
|
|
3
|
+
"version": "0.50.0-develop.a4dde5f252",
|
|
4
4
|
"description": "TypeScript SDK and CLI for building, running, and deploying Phoenix configurator applications.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"salsita",
|
|
@@ -292,8 +292,8 @@
|
|
|
292
292
|
"yaml": "2.9.0",
|
|
293
293
|
"yargs": "17.7.2",
|
|
294
294
|
"zod": "3.25.76",
|
|
295
|
-
"@salsita-ai/
|
|
296
|
-
"@salsita-ai/
|
|
295
|
+
"@salsita-ai/contracts": "0.50.0-develop.a4dde5f252",
|
|
296
|
+
"@salsita-ai/common": "0.50.0-develop.a4dde5f252"
|
|
297
297
|
},
|
|
298
298
|
"devDependencies": {
|
|
299
299
|
"@clerk/clerk-react": "5.61.8",
|