@qpqjs/cli 0.0.0-stage → 0.2.0

package/lib/esm/platforms/types.js

@@ -0,0 +1,6 @@
+export var QpqDeployPlatform;
+(function (QpqDeployPlatform) {
+    QpqDeployPlatform["aws"] = "aws";
+    QpqDeployPlatform["docker"] = "docker";
+})(QpqDeployPlatform || (QpqDeployPlatform = {}));
+//# sourceMappingURL=types.js.map

package/lib/esm/platforms/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/platforms/types.ts"],"names":[],"mappings":"AAOA,MAAM,CAAN,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,gCAAW,CAAA;IACX,sCAAiB,CAAA;AACnB,CAAC,EAHW,iBAAiB,KAAjB,iBAAiB,QAG5B","sourcesContent":["import { QpqAppDeployment } from '@qpqjs/core';\n\nimport { ClearResourcesPlan } from '../lib/clearResourcesPlan';\nimport { DeployPlan, TeardownPlan } from '../lib/deployPrompts';\nimport { GoDockerMode } from '../lib/goDockerMode';\nimport { SetupStep } from '../lib/setupStep';\n\nexport enum QpqDeployPlatform {\n  aws = 'aws',\n  docker = 'docker',\n}\n\n// A deploy platform driver — everything that happens after \"what to deploy\"\n// has been decided. `qpq go` resolves the app + deployment, prompts the plan,\n// then hands off here; the platform comes from the deployment's entry in\n// apps/<app>/deploy.config.json, so an app can move platforms with a config\n// change instead of a different command.\nexport interface QpqPlatformDriver {\n  // Check the deployment's platformSettings and prime the platform's identity\n  // env vars from them. Throws when the entry is incomplete. Runs before any\n  // infrastructure.ts is required, since service configs read those vars at load.\n  prepareDeployment: (deploymentName: string, deployment: QpqAppDeployment) => void;\n\n  // Sequential deploy (`qpq go`).\n  go: (appName: string, plan: DeployPlan) => Promise<void>;\n\n  // Parallel containerized deploy (`qpq go:docker`) — optional; drivers that\n  // have no docker strategy simply omit it. The mode splits the run into a\n  // build half and a deploy half (`--build-only` / `--from-build`); a driver\n  // whose build and deploy cannot be separated refuses anything but 'full'.\n  goDocker?: (appName: string, plan: DeployPlan, mode: GoDockerMode) => Promise<void>;\n\n  // Destroy the web/api/inf stacks for selected services (`qpq teardown`) —\n  // optional; drivers with no teardown strategy simply omit it.\n  teardown?: (appName: string, plan: TeardownPlan) => Promise<void>;\n\n  // Empty the stored data of selected resources without touching the stacks\n  // (`qpq clear-resources`) — optional; drivers with no strategy omit it.\n  clearResources?: (appName: string, plan: ClearResourcesPlan) => Promise<void>;\n\n  // The ordered checklist that takes an empty cloud environment to a deployed\n  // one (`qpq setup`) — optional; drivers with nothing to set up omit it.\n  setupSteps?: (appName: string, deploymentName: string) => Promise<SetupStep[]>;\n\n  // Federated remote publishing (`qpq publish[:build|:upload|:deploy]`).\n  publish: (appName: string, serviceNames: string[]) => Promise<void>;\n  publishBuild: (appName: string, serviceNames: string[]) => Promise<void>;\n  publishUpload: (appName: string, serviceNames: string[]) => Promise<void>;\n  publishDeploy: (appName: string, serviceNames: string[]) => Promise<void>;\n}\n"]}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@qpqjs/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "The qpq CLI — build, dev and deploy orchestration for QPQ apps",
+  "main": "./lib/commonjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/commonjs/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "lib/**/*",
+    "docker/**/*",
+    "templates/**/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "clean": "npx rimraf lib && npx rimraf node_modules",
+    "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:bin-perms",
+    "watch": "tsc -p tsconfig.commonjs.json -w",
+    "build:cjs": "tsc -p tsconfig.commonjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "lint": "npx eslint .",
+    "lint:fix": "npx eslint . --fix",
+    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,scss,md}\"",
+    "build:bin-perms": "node -e \"require('fs').chmodSync('lib/commonjs/bin/qpq.js', 0o755)\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qpqjs/quidproquo.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/qpqjs/quidproquo/issues"
+  },
+  "homepage": "https://github.com/qpqjs/quidproquo#readme",
+  "dependencies": {
+    "@aws-sdk/client-cloudformation": "^3.1093.0",
+    "@aws-sdk/client-dynamodb": "^3.1093.0",
+    "@aws-sdk/client-iam": "^3.1093.0",
+    "@aws-sdk/client-route-53": "^3.1093.0",
+    "@aws-sdk/client-s3": "^3.1093.0",
+    "@aws-sdk/client-sts": "^3.1093.0",
+    "@inquirer/prompts": "^8.5.2",
+    "@rspack/dev-server": "^2.1.0",
+    "aws-cdk": "^2.1132.1",
+    "madge": "^8.0.0",
+    "quidproquo": "0.2.0",
+    "@qpqjs/actionprocessor-aws": "0.2.0",
+    "@qpqjs/config-aws": "0.2.0",
+    "@qpqjs/core": "0.2.0",
+    "@qpqjs/deploy-aws": "0.2.0",
+    "@qpqjs/deploy-rspack": "0.2.0",
+    "@qpqjs/user-script": "0.2.0",
+    "@qpqjs/dev-server": "0.2.0",
+    "@qpqjs/webserver": "0.2.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.8.2"
+  },
+  "devDependencies": {
+    "@rspack/core": "^2.1.2",
+    "@types/node": "^22.13.13",
+    "@qpqjs/tsconfig": "0.2.0"
+  },
+  "bin": {
+    "qpq": "./lib/commonjs/bin/qpq.js"
+  },
+  "peerDependencies": {
+    "@rspack/core": "^2.0.0"
+  }
 }

package/templates/user-script/README.md

@@ -0,0 +1,28 @@
+# __PACKAGE_NAME__
+
+A quidproquo user script. It builds to one JavaScript file that a quidproquo service loads from a storage drive and calls by export name.
+
+## The contract
+
+- The entry is `src/main.ts`. Split the code across other files and folders as you like; the build folds them in.
+- Every export of `src/main.ts` must be a function. A generator export runs as a story: it yields quidproquo actions and its return value is what the caller gets. A plain function export returns its value.
+- Scripts run in a sandbox. The actions available are the pure ones (`askDateNow`, `askNewGuid`, logging, random numbers) and `askNetworkRequest` for calling out over HTTP; a story that yields a file, store or other resource action fails at that point. The service that hosts scripts may offer its own module to import instead (see `defineUserScriptModule`).
+- Import from `@qpqjs/core`. npm packages you add to `package.json` are bundled into the output. Node builtins such as `fs` are refused at build time.
+
+## Build
+
+```
+npm run build
+```
+
+Writes `dist/main.js`, and nothing else. Add `--source-map` to the build to embed a source map in it (no separate `.map` file is written). The build needs no `npm install`: `@qpqjs/core` is provided by the service that runs the script, and the build does not type check. Run `npm install` for editor types and `npm run validate-ts` to type check.
+
+## Run
+
+Copy `dist/main.js` to a storage drive, for example to `scripts/my-script/main.js`, then call it from a story, naming that file and passing the arguments after the export name:
+
+```ts
+const sum = yield* askUserScriptExecute('my-drive', 'scripts/my-script/main.js', 'add', 20, 22);
+```
+
+On the dev server a drive is a folder under `.qpq-runtime/<app>/storage/<service>/<drive>/`, so `qpq script:build . --out <that folder>/scripts/my-script` publishes locally to `scripts/my-script/main.js`.

package/templates/user-script/gitignore

@@ -0,0 +1,2 @@
+dist
+node_modules

package/templates/user-script/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "description": "A quidproquo user script: functions called by name from a storage drive",
+  "scripts": {
+    "build": "qpq script:build .",
+    "validate-ts": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@qpqjs/core": "__QPQ_VERSION__"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2"
+  }
+}

package/templates/user-script/src/main.ts

@@ -0,0 +1,15 @@
+import { askDateNow, AskResponse } from '@qpqjs/core';
+
+// Every export of this file is callable by name through askUserScriptExecute. A
+// generator export is a story: it yields quidproquo actions and its return value is
+// the result. A plain function export just returns its value. Scripts run in a sandbox
+// whose actions are the pure ones (date, guid, log, math) and network requests, so a story
+// may stamp a time, mint an id or call an HTTP API, but not read or write the service's
+// resources.
+
+export const add = (a: number, b: number): number => a + b;
+
+export function* stampedGreeting(name: string): AskResponse<string> {
+  const now = yield* askDateNow();
+  return `hello ${name} @ ${now}`;
+}

package/templates/user-script/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}